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

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

    <sect2 id="zend.codegenerator.reference.abstracts">
        <title>Classes abstraites et interfaces</title>

        <sect3 id="zend.codegenerator.reference.abstracts.abstract">
            <title>Zend_CodeGenerator_Abstract</title>

            <para>
                La classe de base de CodeGenerator dont toutes les classes héritent. Elle
                propose l'<acronym>API</acronym> suivante&#160;:
            </para>

            <programlisting language="php"><![CDATA[
abstract class Zend_CodeGenerator_Abstract
{
    final public function __construct(Array $options = array())
    public function setOptions(Array $options)
    public function setSourceContent($sourceContent)
    public function getSourceContent()
    protected function _init()
    protected function _prepare()
    abstract public function generate();
    final public function __toString()
}
]]></programlisting>

            <para>
                Le constructeur appelle <methodname>_init()</methodname> (restée vide, à écrire
                dans les classes concrètes), puis passe le paramètre <varname>$options</varname> à
                <methodname>setOptions()</methodname>, et enfin appelle
                <methodname>_prepare()</methodname> (encore une
                fois, vide, à écrire dans les classes concrètes).
            </para>

            <para>
                Comme partout dans Zend Framework, <methodname>setOptions()</methodname> compare les
                clés du tableau passé comme paramètre à des setters de la classe, et passe donc la
                valeur à la bonne méthode si trouvée.
            </para>

            <para>
                <methodname>__toString()</methodname> est marquée final, et proxie vers
                <methodname>generate()</methodname>.
            </para>

            <para>
                <methodname>setSourceContent()</methodname> et
                <methodname>getSourceContent()</methodname> permettent
                soit de définir le contenu par défaut soit de remplacer ce contenu par la tâche de
                génération.
            </para>
        </sect3>

        <sect3 id="zend.codegenerator.reference.abstracts.php-abstract">
            <title>Zend_CodeGenerator_Php_Abstract</title>

            <para>
                <classname>Zend_CodeGenerator_Php_Abstract</classname> étend
                <classname>Zend_CodeGenerator_Abstract</classname> et ajoute des méthodes permettant
                de savoir si le contenu a changé et aussi le nombre d'indentation à utiliser avant
                chaque ligne de code à générer. L'<acronym>API</acronym> est la suivante&#160;:
            </para>

            <programlisting language="php"><![CDATA[
abstract class Zend_CodeGenerator_Php_Abstract
    extends Zend_CodeGenerator_Abstract
{
    public function setSourceDirty($isSourceDirty = true)
    public function isSourceDirty()
    public function setIndentation($indentation)
    public function getIndentation()
}
]]></programlisting>
        </sect3>

        <sect3 id="zend.codegenerator.reference.abstracts.php-member-abstract">
            <title>Zend_CodeGenerator_Php_Member_Abstract</title>

            <para>
                <classname>Zend_CodeGenerator_Php_Member_Abstract</classname> est une classe
                de base pour générer des propriétés ou des méthodes de classe, et propose des
                accesseurs et des mutateurs pour créer la visibilité, l'abstraction, la staticité ou
                la finalité. L'<acronym>API</acronym> est la suivante&#160;:
            </para>

            <programlisting language="php"><![CDATA[
abstract class Zend_CodeGenerator_Php_Member_Abstract
    extends Zend_CodeGenerator_Php_Abstract
{
    public function setAbstract($isAbstract)
    public function isAbstract()
    public function setStatic($isStatic)
    public function isStatic()
    public function setVisibility($visibility)
    public function getVisibility()
    public function setName($name)
    public function getName()
}
]]></programlisting>
        </sect3>
    </sect2>

    <sect2 id="zend.codegenerator.reference.concrete">
        <title>Classes CodeGenerator concrêtes</title>

        <sect3 id="zend.codegenerator.reference.concrete.php-body">
            <title>Zend_CodeGenerator_Php_Body</title>

            <para>
                <classname>Zend_CodeGenerator_Php_Body</classname> est utilisée pour générer
                du code procédural à inclure dans un fichier. Vous passez
                donc simplement du contenu à cet objet, qui vous le ressortira une fois son
                <methodname>generate()</methodname> appelé.
            </para>

            <para>L'<acronym>API</acronym> de cette classe est comme suit&#160;:</para>

            <programlisting language="php"><![CDATA[
class Zend_CodeGenerator_Php_Body extends Zend_CodeGenerator_Php_Abstract
{
    public function setContent($content)
    public function getContent()
    public function generate()
}
]]></programlisting>
        </sect3>

        <sect3 id="zend.codegenerator.reference.concrete.php-class">
            <title>Zend_CodeGenerator_Php_Class</title>

            <para>
                <classname>Zend_CodeGenerator_Php_Class</classname> est utilisée pour générer
                du code de classes <acronym>PHP</acronym>. Les fonctions de bases génèrent la
                classe <acronym>PHP</acronym> elle-même, ainsi que ses commentaires
                <acronym>PHP</acronym> DocBlock. Vous pouvez bien sûr spécifier
                la classe comme abstraite, finale, ou encore lui rajouter des
                constantes&#160;/&#160;attributs&#160;/&#160;méthodes sous
                forme d'autres objets décrits eux aussi dans ce chapitre.
            </para>

            <para>Voici l'<acronym>API</acronym>&#160;:</para>

            <programlisting language="php"><![CDATA[
class Zend_CodeGenerator_Php_Class extends Zend_CodeGenerator_Php_Abstract
{
    public static function fromReflection(
        Zend_Reflection_Class $reflectionClass
    )
    public function setDocblock(Zend_CodeGenerator_Php_Docblock $docblock)
    public function getDocblock()
    public function setName($name)
    public function getName()
    public function setAbstract($isAbstract)
    public function isAbstract()
    public function setExtendedClass($extendedClass)
    public function getExtendedClass()
    public function setImplementedInterfaces(Array $implementedInterfaces)
    public function getImplementedInterfaces()
    public function setProperties(Array $properties)
    public function setProperty($property)
    public function getProperties()
    public function getProperty($propertyName)
    public function setMethods(Array $methods)
    public function setMethod($method)
    public function getMethods()
    public function getMethod($methodName)
    public function hasMethod($methodName)
    public function isSourceDirty()
    public function generate()
}
]]></programlisting>

            <para>
                La méthode <methodname>setProperty()</methodname> accepte soit un tableau qui peut
                être utilisé pour générer une instance de
                <classname>Zend_CodeGenerator_Php_Property</classname>, soit directement une
                instance de <classname>Zend_CodeGenerator_Php_Property</classname>.
                <methodname>setMethod()</methodname> se manipule de la même manière, et utilise une
                instance de <classname>Zend_CodeGenerator_Php_Method</classname>.
            </para>

            <para>
                A noter que <methodname>setDocBlock()</methodname> attend une instance de
                <classname>Zend_CodeGenerator_Php_DocBlock</classname>.
            </para>
        </sect3>

        <sect3 id="zend.codegenerator.reference.concrete.php-docblock">
            <title>Zend_CodeGenerator_Php_Docblock</title>

            <para>
                <classname>Zend_CodeGenerator_Php_Docblock</classname> est utilisée pour
                générer des éléments <acronym>PHP</acronym> arbitraire, y compris les commentaires
                de description longs ou courts.
            </para>

            <para>
                Les tags annotation doivent être spécifiés via <methodname>setTag()</methodname> ou
                <methodname>setTags()</methodname> qui prennent en paramètre un objet
                <classname>Zend_CodeGenerator_Php_Docblock_Tag</classname> ou un tableau qui
                permettra sa construction.
            </para>

            <para>Voici l'<acronym>API</acronym>&#160;:</para>

            <programlisting language="php"><![CDATA[
class Zend_CodeGenerator_Php_Docblock extends Zend_CodeGenerator_Php_Abstract
{
    public static function fromReflection(
        Zend_Reflection_Docblock $reflectionDocblock
    )
    public function setShortDescription($shortDescription)
    public function getShortDescription()
    public function setLongDescription($longDescription)
    public function getLongDescription()
    public function setTags(Array $tags)
    public function setTag($tag)
    public function getTags()
    public function generate()
}
]]></programlisting>
        </sect3>

        <sect3 id="zend.codegenerator.reference.concrete.php-docblock-tag">
            <title>Zend_CodeGenerator_Php_Docblock_Tag</title>

            <para>
                <classname>Zend_CodeGenerator_Php_Docblock_Tag</classname> est utilisée pour
                créer des balises d'annotation <acronym>PHP</acronym> DocBlck. Les balises doivent
                posséder un nom (la partie qui suit immédiatement le '@') et une description
                (ce qui suit le tag).
            </para>

            <para>Voici l'<acronym>API</acronym>&#160;:</para>

            <programlisting language="php"><![CDATA[
class Zend_CodeGenerator_Php_Docblock_Tag
    extends Zend_CodeGenerator_Php_Abstract
{
    public static function fromReflection(
        Zend_Reflection_Docblock_Tag $reflectionTag
    )
    public function setName($name)
    public function getName()
    public function setDescription($description)
    public function getDescription()
    public function generate()
}
]]></programlisting>
        </sect3>

        <sect3 id="zend.codegenerator.reference.concrete.php-docblock-tag-param">
            <title>Zend_CodeGenerator_Php_DocBlock_Tag_Param</title>

            <para>
                <classname>Zend_CodeGenerator_Php_DocBlock_Tag_Param</classname> est une
                version spéciale de <classname>Zend_CodeGenerator_Php_DocBlock_Tag</classname>, et
                permet de représenter un paramètre d'une méthode. Le nom de la balise est donc
                connu, mais des informations additionnelles sont requises&#160;: le nom du
                paramètre et le type de données qu'il représente.
            </para>

            <para>L'<acronym>API</acronym> de cette classe est la suivante&#160;:</para>

            <programlisting language="php"><![CDATA[
class Zend_CodeGenerator_Php_Docblock_Tag_Param
    extends Zend_CodeGenerator_Php_Docblock_Tag
{
    public static function fromReflection(
        Zend_Reflection_Docblock_Tag $reflectionTagParam
    )
    public function setDatatype($datatype)
    public function getDatatype()
    public function setParamName($paramName)
    public function getParamName()
    public function generate()
}
]]></programlisting>
        </sect3>

        <sect3 id="zend.codegenerator.reference.concrete.php-docblock-tag-return">
            <title>Zend_CodeGenerator_Php_DocBlock_Tag_Return</title>

            <para>
                <classname>Zend_CodeGenerator_Php_Docblock_Tab_Return</classname> est une
                variante qui permet de modéliser la valeur de retour d'une méthode. Dans ce cas, le
                nom de la balise est connu ('return') mais pas le type de retour.
            </para>

            <para>Voici l'<acronym>API</acronym>&#160;:</para>

            <programlisting language="php"><![CDATA[
class Zend_CodeGenerator_Php_Docblock_Tag_Param
    extends Zend_CodeGenerator_Php_Docblock_Tag
{
    public static function fromReflection(
        Zend_Reflection_Docblock_Tag $reflectionTagReturn
    )
    public function setDatatype($datatype)
    public function getDatatype()
    public function generate()
}
]]></programlisting>
        </sect3>

        <sect3 id="zend.codegenerator.reference.concrete.php-file">
            <title>Zend_CodeGenerator_Php_File</title>

            <para>
                <classname>Zend_CodeGenerator_Php_File</classname> est utilisée pour générer
                le contenu complet d'un fichier <acronym>PHP</acronym>. Le fichier peut contenir
                des classes, du code <acronym>PHP</acronym> ou encore des commentaires PHPDoc.
            </para>

            <para>
                Pour ajouter des classes, vous devrez soit passer un tableau d'informations à
                passer au constructeur de <classname>Zend_CodeGenerator_Php_Class</classname>, soit
                un objet de cette dernière classe directement. Idem concernant les commentaires
                PHPDoc et la classe <classname>Zend_CodeGenerator_Php_Docblock</classname>
            </para>

            <para>Voici l'<acronym>API</acronym> de la classe&#160;:</para>

            <programlisting language="php"><![CDATA[
class Zend_CodeGenerator_Php_File extends Zend_CodeGenerator_Php_Abstract
{
    public static function fromReflectedFilePath(
        $filePath,
        $usePreviousCodeGeneratorIfItExists = true,
        $includeIfNotAlreadyIncluded = true)
    public static function fromReflection(Zend_Reflection_File $reflectionFile)
    public function setDocblock(Zend_CodeGenerator_Php_Docblock $docblock)
    public function getDocblock()
    public function setRequiredFiles($requiredFiles)
    public function getRequiredFiles()
    public function setClasses(Array $classes)
    public function getClass($name = null)
    public function setClass($class)
    public function setFilename($filename)
    public function getFilename()
    public function getClasses()
    public function setBody($body)
    public function getBody()
    public function isSourceDirty()
    public function generate()
}
]]></programlisting>
        </sect3>

        <sect3 id="zend.codegenerator.reference.concrete.php-member-container">
            <title>Zend_CodeGenerator_Php_Member_Container</title>

            <para>
                <classname>Zend_CodeGenerator_Php_Member_Container</classname> est utilisée en
                interne par <classname>Zend_CodeGenerator_Php_Class</classname> pour garder une
                trace des attributs et des méthodes de classe. Ceux-ci sont indéxés par nom.
            </para>

            <para>Voici l'<acronym>API</acronym> de cette classe&#160;:</para>

            <programlisting language="php"><![CDATA[
class Zend_CodeGenerator_Php_Member_Container extends ArrayObject
{
    public function __construct($type = self::TYPE_PROPERTY)
}
]]></programlisting>
        </sect3>

        <sect3 id="zend.codegenerator.reference.concrete.php-method">
            <title>Zend_CodeGenerator_Php_Method</title>

            <para>
                <classname>Zend_CodeGenerator_Php_Method</classname> est utilisée pour décrire
                une méthode d'une classe, et va générer son code, et ses éventuels commentaires
                PHPDoc. La visibilité et le statut (abstraite, finale, statique) peuvent être
                spécifiées par la classe parente
                <classname>Zend_CodeGenerator_Php_Member_Abstract</classname>. Enfin, il est aussi
                possible de spécifier les paramètres de la méthodes, et sa valeur de retour.
            </para>

            <para>
                Les paramètres peuvent être indiqués via <methodname>setParameter()</methodname> ou
                <methodname>setParameters()</methodname> qui acceptent soit des tableaux décrivant
                les paramètres à passer au constructeur
                de<classname>Zend_CodeGenerator_Php_Parameter</classname>, soit des objets de cette
                dernière classe.
            </para>

            <para>L'<acronym>API</acronym> de cette classe est la suivante&#160;:</para>

            <programlisting language="php"><![CDATA[
class Zend_CodeGenerator_Php_Method
    extends Zend_CodeGenerator_Php_Member_Abstract
{
    public static function fromReflection(
        Zend_Reflection_Method $reflectionMethod
    )
    public function setDocblock(Zend_CodeGenerator_Php_Docblock $docblock)
    public function getDocblock()
    public function setFinal($isFinal)
    public function setParameters(Array $parameters)
    public function setParameter($parameter)
    public function getParameters()
    public function setBody($body)
    public function getBody()
    public function generate()
}
]]></programlisting>
        </sect3>

        <sect3 id="zend.codegenerator.reference.concrete.php-parameter">
            <title>Zend_CodeGenerator_Php_Parameter</title>

            <para>
                <classname>Zend_CodeGenerator_Php_Parameter</classname> est utilisée pour
                décrire un paramètre de méthode. Chacun doit avoir une position (sinon l'ordre de
                leur enregistrement sera utilisé par défaut), une valeur par défaut, un type et
                enfin un nom.
            </para>

            <para>Voici l'<acronym>API</acronym>&#160;:</para>

            <programlisting language="php"><![CDATA[
class Zend_CodeGenerator_Php_Parameter extends Zend_CodeGenerator_Php_Abstract
{
    public static function fromReflection(
        Zend_Reflection_Parameter $reflectionParameter
    )
    public function setType($type)
    public function getType()
    public function setName($name)
    public function getName()
    public function setDefaultValue($defaultValue)
    public function getDefaultValue()
    public function setPosition($position)
    public function getPosition()
    public function getPassedByReference()
    public function setPassedByReference($passedByReference)
    public function generate()
}
]]></programlisting>

            <para>
                Plusieurs problèmes peuvent apparaître lorsque l'on veut paramétrer un
                <constant>NULL</constant>, un booléen ou un tableau en tant que valeur par
                défaut. Pour ceci le conteneur
                <classname>Zend_CodeGenerator_Php_ParameterDefaultValue</classname> peut être
                utilisé, par exemple&#160;:
            </para>

            <programlisting language="php"><![CDATA[
$parameter = new Zend_CodeGenerator_Php_Parameter();
$parameter->setDefaultValue(
    new Zend_CodeGenerator_Php_Parameter_DefaultValue("null")
);
$parameter->setDefaultValue(
    new Zend_CodeGenerator_Php_Parameter_DefaultValue("array('foo', 'bar')")
);
]]></programlisting>

            <para>
                En interne <methodname>setDefaultValue()</methodname> convertit aussi les valeurs
                qui peuvent être exprimées en <acronym>PHP</acronym> dans le conteneur.
            </para>
        </sect3>

        <sect3 id="zend.codegenerator.reference.concrete.php-property">
            <title>Zend_CodeGenerator_Php_Property</title>

            <para>
                <classname>Zend_CodeGenerator_Php_Property</classname> est utilisée pour
                décrire une propriété, nous entendons par là une variable ou
                une constante. Une valeur par défaut peut alors être
                spécifiée. La visibilité de la propriété peut être définie par la classe parente,
                <classname>Zend_CodeGenerator_Php_Member_Abstract</classname>.
            </para>

            <para>Voici l'<acronym>API</acronym>&#160;:</para>

            <programlisting language="php"><![CDATA[
class Zend_CodeGenerator_Php_Property
    extends Zend_CodeGenerator_Php_Member_Abstract
{
    public static function fromReflection(
        Zend_Reflection_Property $reflectionProperty
    )
    public function setConst($const)
    public function isConst()
    public function setDefaultValue($defaultValue)
    public function getDefaultValue()
    public function generate()
}
]]></programlisting>
        </sect3>
    </sect2>
</sect1>