repo_zf1/documentation/manual/fr/module_specs/Zend_Reflection-Reference.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.reflection.reference">
    <title>Réference de Zend_Reflection</title>

    <para>
        Les classes de <classname>Zend_Reflection</classname> reprennent l'API de <ulink
        url="http://php.net/reflection">la Reflection <acronym>PHP</acronym></ulink> - mais avec une différence
        importante : la Reflection <acronym>PHP</acronym> ne propose pas de manière d'introspecter les tags de
        documentation PHPDoc, ni les types des variables paramètres ou encore les types de retour
        des fonctions.
    </para>

    <para>
        <classname>Zend_Reflection</classname> analyse les commentaires PHPDoc pour déterminer les types
        des variables passées en paramètres ou de retour. Plus spécialement, les annotations
        <code>@param</code> et <code>@return</code> sont utilisées, même s'il reste possible
        d'analyser les autres blocs de commentaire, ainsi que leurs descriptions respectives.
    </para>

    <para>
        Chaque objet de réflexion dans <classname>Zend_Reflection</classname>, surcharge la méthode
        <methodname>getDocblock()</methodname> pour retourner une instance de
        <classname>Zend_Reflection_Docblock</classname>. Cette classe propose alors l'introspection des blocs
        de commentaires et notamment des tags PHPDoc.
    </para>

    <para>
        <classname>Zend_Reflection_File</classname> est une nouvelle classe qui permet d'introspecter
        les fichiers <acronym>PHP</acronym> à la recherche de classes, fonctions ou encore code global <acronym>PHP</acronym> contenu à
        l'intérieur.
    </para>

    <para>
        Enfin, la plupart des méthodes qui retournent des objets réflexion acceptent un second
        paramètre permettant de spécifier la classe qui sera instanciée pour créer de tels
        objets.
    </para>

    <sect2 id="zend.reflection.reference.docblock">
        <title>Zend_Reflection_Docblock</title>

        <para>
            <classname>Zend_Reflection_Docblock</classname> est le coeur de la valeur ajoutée par
            <classname>Zend_Reflection</classname> par rapport à la Reflection <acronym>PHP</acronym>. Voici les méthodes
            proposées&#160;:
        </para>

        <itemizedlist>
            <listitem>
                <para><methodname>getContents()</methodname>&#160;: retourne tout le contenu du bloc.</para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getStartLine()</methodname>&#160;: retourne la position de départ du bloc dans
                    le fichier.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getEndLine()</methodname>&#160;: retourne la position de fin du bloc dans le
                    fichier.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getShortDescription()</methodname>&#160;: récupère la description courte (en
                    général la première ligne de commentaire).
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getLongDescription()</methodname>&#160;: récupère la description longue du
                    bloc.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>hasTag($name)</methodname>&#160;: détermine si le bloc possède un tag
                    particulier.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getTag($name)</methodname>&#160;: Récupère un tag particulier ou
                    <constant>FALSE</constant> si celui-ci est absent.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getTags($filter)</methodname>&#160;: Récupère tous les tags qui correspondent au
                    filtre <varname>$filter</varname>. Le type de retour est un tableau d'objets
                    <classname>Zend_Reflection_Docblock_Tag</classname>.
                </para>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.reflection.reference.docblock-tag">
        <title>Zend_Reflection_Docblock_Tag</title>

        <para>
            <classname>Zend_Reflection_Docblock_Tag</classname> propose la réflexion pour un tag
            individuel. La plupart des tags se composent d'un nom et d'un description. Dans le cas
            de certains tags spéciaux, la classe propose une méthode de fabrique qui retourne la
            bonne instance.
        </para>

        <para>Voici les méthodes de <classname>Zend_Reflection_Docblock_Tag</classname>&#160;:</para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>factory($tagDocblockLine)</methodname>&#160;: instancie la bonne classe de
                    reflection pour le tag correspondant et en retourne l'objet.
                </para>
            </listitem>

            <listitem>
                <para><methodname>getName()</methodname>&#160;: retourne le nom du tag.</para>
            </listitem>

            <listitem>
                <para><methodname>getDescription()</methodname>&#160;: retourne la description du tag.</para>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.reflection.reference.docblock-tag-param">
        <title>Zend_Reflection_Docblock_Tag_Param</title>

        <para>
            <classname>Zend_Reflection_Docblock_Tag_Param</classname> est une version spéciale de
            <classname>Zend_Reflection_Docblock_Tag</classname>. La description du tag <code>@param</code>
            consiste en un type, un nom de variable et une description. Elle ajoute les méthodes
            suivantes à <classname>Zend_Reflection_Docblock_Tag</classname>&#160;:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>getType()</methodname>&#160;: Retourne le type de la variable considérée par le
                    tag.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getVariableName()</methodname>&#160;: Retourne le nom de la variable considérée
                    par le tag.
                </para>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.reflection.reference.docblock-tag-return">
        <title>Zend_Reflection_Docblock_Tag_Return</title>

        <para>
            Comme <classname>Zend_Reflection_Docblock_Tag_Param</classname>,
            <classname>Zend_Reflection_Docblock_Tag_Return</classname> est une version spéciale de
            <classname>Zend_Reflection_Docblock_Tag</classname>. Le tag <code>@return</code> consiste en un
            type de retour et une description. Elle ajoute les méthodes suivantes à
            <classname>Zend_Reflection_Docblock_Tag</classname>&#160;:
        </para>

        <itemizedlist>
            <listitem>
                <para><methodname>getType()</methodname>: retourne le type de retour.</para>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.reflection.reference.file">
        <title>Zend_Reflection_File</title>

        <para>
            <classname>Zend_Reflection_File</classname> propose l'introspection de fichiers <acronym>PHP</acronym>. Grâce à
            cela, vous pouvez déterminer les classes, fonctions ou le code pur <acronym>PHP</acronym> contenus dans un
            fichier <acronym>PHP</acronym> donné. Voici les méthodes proposées&#160;:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>getFileName()</methodname>&#160;: retourne le nom du fichier en cours de
                    réflexion.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getStartLine()</methodname>&#160;: retourne la ligne de démarrage du fichier
                    (toujours "1").
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getEndLine()</methodname>&#160;: retourne la dernière ligne du fichier, donc le
                    nombre de lignes.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getDocComment($reflectionClass = 'Zend_Reflection_Docblock')</methodname>&#160;:
                    retourne un objet de réflection de commentaire PHPDoc du fichier en cours
                    d'analyse.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getClasses($reflectionClass = 'Zend_Reflection_Class')</methodname>&#160;:
                    retourne un tableau d'objets de réflexion de classe, pour les classes contenues
                    dans le fichier en cours d'analyse.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getFunctions($reflectionClass = 'Zend_Reflection_Function')</methodname>&#160;:
                    retourne un tableau d'objets de réflexion de fonction, pour les fonctions
                    contenues dans le fichier en cours d'analyse.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>getClass($name = null, $reflectionClass =
                    'Zend_Reflection_Class')</code>&#160;: retourne l'objet de réflexion pour la
                    classe contenue dans le fichier en cours d'analyse.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getContents()</methodname>&#160;: retourne tout le contenu du fichier en cours
                    d'analyse.
                </para>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.reflection.reference.class">
        <title>Zend_Reflection_Class</title>

        <para>
            <classname>Zend_Reflection_Class</classname> étend <code>ReflectionClass</code>, et propose
            son <acronym>API</acronym>. Elle ajoute juste une méthode, <methodname>getDeclaringFile()</methodname>, qui peut être
            utilisée pour créer un objet <classname>Zend_Reflection_File</classname>.
        </para>

        <para>
            Aussi, les méthodes suivantes proposent un argument supplémentaire pour spécifier
            sa propre classe de réflexion:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>getDeclaringFile($reflectionClass = 'Zend_Reflection_File')</methodname>
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getDocblock($reflectionClass = 'Zend_Reflection_Docblock')</methodname>
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getInterfaces($reflectionClass = 'Zend_Reflection_Class')</methodname>
                </para>
            </listitem>

            <listitem>
                <para><methodname>getMethod($reflectionClass = 'Zend_Reflection_Method')</methodname></para>
            </listitem>

            <listitem>
                <para>
                    <code>
                        getMethods($filter = -1, $reflectionClass = 'Zend_Reflection_Method')
                    </code>
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getParentClass($reflectionClass = 'Zend_Reflection_Class')</methodname>
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getProperty($name, $reflectionClass = 'Zend_Reflection_Property')</methodname>
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>
                        getProperties($filter = -1, $reflectionClass = 'Zend_Reflection_Property')
                    </code>
                </para>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.reflection.reference.extension">
        <title>Zend_Reflection_Extension</title>

        <para>
            <classname>Zend_Reflection_Extension</classname> étend <code>ReflectionExtension</code> et
            propose son <acronym>API</acronym>. Elle surcharge les méthodes suivantes afin d'ajouter un paramètre
            permettant de spécifier sa propre classe de réflexion&#160;:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>getFunctions($reflectionClass = 'Zend_Reflection_Function')</methodname>&#160;:
                    retourne un tableau d'objets réflexion représentants les fonctions définies par
                    l'extension en question.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getClasses($reflectionClass = 'Zend_Reflection_Class')</methodname>&#160;:
                    retourne un tableau d'objets réflexion représentants les classes définies par
                    l'extension en question.
                </para>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.reflection.reference.function">
        <title>Zend_Reflection_Function</title>

        <para>
            <classname>Zend_Reflection_Function</classname> ajoute une méthode pour retrouver le type de
            retour de la fonction introspéctée, et surcharge d'autres méthodes pour proposer de
            passer en paramètre une classe de réflexion à utiliser.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>getDocblock($reflectionClass = 'Zend_Reflection_Docblock')</methodname>:
                    Retourne un objet représentant les blocs de documentation.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>getParameters($reflectionClass =
                    'Zend_Reflection_Parameter')</code>&#160;: Retourne un tableau représentant les
                    paramètres de la fonction analysée sous forme d'objets réflexion.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getReturn()</methodname>&#160;: Retourne le type de retour sous forme d'objet
                    réflexion
                </para>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.reflection.reference.method">
        <title>Zend_Reflection_Method</title>

        <para>
            <classname>Zend_Reflection_Method</classname> reprend l'API de
            <classname>Zend_Reflection_Function</classname> et surcharge la méthode suivante:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>getParentClass($reflectionClass = 'Zend_Reflection_Class')</methodname>&#160;:
                    Retourne un objet réflexion de la classe parente
                </para>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.reflection.reference.parameter">
        <title>Zend_Reflection_Parameter</title>

        <para>
            <classname>Zend_Reflection_Parameter</classname> ajoute une méthode pour retrouver le type
            d'un paramètre, et aussi surcharge certaines méthodes en rajoutant un paramètre
            permettant de spécifier sa propre classe de réflexion.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>getDeclaringClass($reflectionClass =
                    'Zend_Reflection_Class')</code>&#160;: retourne un objet réflexion représentant
                    la classe de déclaration du paramètre (si disponible).
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getClass($reflectionClass = 'Zend_Reflection_Class')</methodname>&#160;:
                    retourne un objet réflexion représentant la classe de l'objet passé comme
                    paramètre (si disponible).
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>getDeclaringFunction($reflectionClass =
                    'Zend_Reflection_Function')</code>&#160;: retourne un objet réflexion
                    représentant la fonction passée comme paramètre (si disponible).
                </para>
            </listitem>

            <listitem>
                <para><methodname>getType()</methodname>&#160;: retourne le type du paramètre.</para>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.reflection.reference.property">
        <title>Zend_Reflection_Property</title>

        <para>
            <classname>Zend_Reflection_Property</classname> surcharge une seule méthode afin de pouvoir
            spécifier le type de classe de retour&#160;:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>getDeclaringClass($reflectionClass =
                    'Zend_Reflection_Class')</code>&#160;: Retourne un objet réflexion représentant
                    la classe de l'objet passé comme paramètre (si disponible).
                </para>
            </listitem>
        </itemizedlist>
    </sect2>
</sect1>