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

<?xml version="1.0" encoding="UTF-8"?>
<!-- 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'API suivante:
            </para>

            <programlisting role="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 <code>_init()</code> (restée vide, à
                écrire dans les classes concrêtes),
                puis passe le paramètre <code>$options</code> à
                <code>setOptions()</code>, et enfin appelle
                <code>_prepare()</code> (encore une fois, vide, à écrire dans les
                classes concrêtes).
            </para>

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

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

            <para>
                <code>setSourceContent()</code> et
                <code>getSourceContent()</code> 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'API est la suivante:
            </para>

            <programlisting role="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'API est la suivante:
            </para>

            <programlisting role="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 PHP procédural à inclure dans un fichier. Vous passez donc simplement
                du contenu à cet objet, qui vous le resortira une fois son
                <code>generate()</code> appelé.
            </para>

            <para>
                L'API de cette classe est comme suit:
            </para>

            <programlisting role="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 PHP. Les fonctions de bases génèrent la classe
                elle-même, ainsi que ses commentaires PHPDoc. Vous pouvez bien sûr
                spécifier la classe comme abstraite, finale, ou encore lui rajouter des
                constantes/attributs/méthodes sous forme d'autres objets décrits eux
                aussi dans ce chapitre.
            </para>

            <para>
                Voici l'API:
            </para>

            <programlisting role="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 <code>setProperty()</code> 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>.
                <code>setMethod()</code> se manipule de la même manière, et utilise une instance de
                <classname>Zend_CodeGenerator_Php_Method</classname>.
            </para>

            <para>
                A noter que <code>setDocBlock()</code> 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 du code
                PHPDoc arbitraire, y compris les commentaires de description longs ou courts.
            </para>

            <para>
                Les tags annotation doivent être spécifiés via <code>setTag()</code> ou <code>setTags()</code>
                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'API:
            </para>

            <programlisting role="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 tags d'annotation PHPdoc. Les tags doivent posséder un nom (la partie qui suit 
                immédiatement le '@') et une description (ce qui suit le tag).
            </para>

            <para>
                Voici l'API:
            </para>

            <programlisting role="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 du tag est donc connu,
                mais des informations additionnelles sont requises : le nom du paramètre
                et le type de données qu'il représente.
            </para>

            <para>
                L'API de cette classe est la suivante:
            </para>

            <programlisting role="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 du tag
                est connu ('return') mais pas le type de retour.
            </para>

            <para>
                Voici l'API:
            </para>

            <programlisting role="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 PHP. Le fichier peut contenir des classes, du code
                PHP 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'API de la classe:
            </para>

            <programlisting role="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'API de cette classe:
            </para>

            <programlisting role="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 <code>setParameter()</code> ou
                <code>setParameters()</code> 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'API de cette classe est la suivante:
            </para>

            <programlisting role="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'API:
            </para>

            <programlisting role="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 generate()
}
]]></programlisting>
        </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é
                PHP, nous entendons par là une variable ou une constante PHP. 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'API:
            </para>

            <programlisting role="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>