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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.codegenerator.reference">
    <title>Zend_CodeGenerator Reference</title>

    <sect2 id="zend.codegenerator.reference.abstracts">
        <title>Abstract Classes and Interfaces</title>

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

            <para>
                The base class from which all CodeGenerator classes inherit
                provides the minimal functionality necessary. It's <acronym>API</acronym> is as
                follows:
            </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>
                The constructor first calls <methodname>_init()</methodname> (which is left
                empty for the concrete extending class to implement), then
                passes the <varname>$options</varname> parameter to
                <methodname>setOptions()</methodname>, and finally calls
                <methodname>_prepare()</methodname> (again, to be implemented by an
                extending class).
            </para>

            <para>
                Like most classes in Zend Framework, <methodname>setOptions()</methodname>
                compares an option key to existing setters in the class, and
                passes the value on to that method if found.
            </para>

            <para>
                <methodname>__toString()</methodname> is marked as final, and proxies to
                <methodname>generate()</methodname>.
            </para>

            <para>
                <methodname>setSourceContent()</methodname> and
                <methodname>getSourceContent()</methodname> are intended to either set the
                default content for the code being generated, or to replace said
                content once all generation tasks are complete.
            </para>
        </sect3>

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

            <para>
                <classname>Zend_CodeGenerator_Php_Abstract</classname> extends
                <classname>Zend_CodeGenerator_Abstract</classname>, and adds some
                properties for tracking whether content has changed as well as
                the amount of indentation that should appear before generated
                content. Its <acronym>API</acronym> is as follows:
            </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> is a base
                class for generating class members -- properties and methods --
                and provides accessors and mutators for establishing visibility;
                whether or not the member is abstract, static, or final; and the
                name of the member. Its <acronym>API</acronym> is as follows:
            </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>Concrete CodeGenerator Classes</title>

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

            <para>
                <classname>Zend_CodeGenerator_Php_Body</classname> is intended for
                generating arbitrary procedural code to include within a file.
                As such, you simply set content for the object, and it will
                return that content when you invoke <methodname>generate()</methodname>.
            </para>

            <para>
                The <acronym>API</acronym> of the class is as follows:
            </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> is intended for
                generating <acronym>PHP</acronym> classes. The basic functionality just generates
                the <acronym>PHP</acronym> class itself, as well as optionally the related
                <acronym>PHP</acronym> DocBlock. Classes may implement or inherit from other
                classes, and may be marked as abstract. Utilizing other code generator
                classes, you can also attach class constants, properties, and
                methods.
            </para>

            <para>
                The <acronym>API</acronym> is as follows:
            </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>
                The <methodname>setProperty()</methodname> method accepts an array of
                information that may be used to generate a
                <classname>Zend_CodeGenerator_Php_Property</classname> instance -- or
                simply an instance of
                <classname>Zend_CodeGenerator_Php_Property</classname>.
                Likewise, <methodname>setMethod()</methodname> accepts either an array of
                information for generating a
                <classname>Zend_CodeGenerator_Php_Method</classname> instance or a
                concrete instance of that class.
            </para>

            <para>
                Note that <methodname>setDocBlock()</methodname> expects an instance of
                <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> can be used to
                generate arbitrary <acronym>PHP</acronym> docblocks, including all the standard
                docblock features: short and long descriptions and annotation
                tags.
            </para>

            <para>
                Annotation tags may be set using the <methodname>setTag()</methodname> and
                <methodname>setTags()</methodname> methods; these each take either an array
                describing the tag that may be passed to the
                <classname>Zend_CodeGenerator_Php_Docblock_Tag</classname> constructor, or
                an instance of that class.
            </para>

            <para>
                The <acronym>API</acronym> is as follows:
            </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> is intended for
                creating arbitrary annotation tags for inclusion in <acronym>PHP</acronym>
                docblocks. Tags are expected to contain a name (the portion
                immediately following the '@' symbol) and a description
                (everything following the tag name).
            </para>

            <para>
                The class <acronym>API</acronym> is as follows:
            </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> is a
                specialized version of
                <classname>Zend_CodeGenerator_Php_DocBlock_Tag</classname>, and represents
                a method parameter. The tag name is therefor known ("param"),
                but due to the format of this annotation tag, additional
                information is required in order to generate it: the parameter
                name and data type it represents.
            </para>

            <para>
                The class <acronym>API</acronym> is as follows:
            </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>
                Like the param docblock tag variant,
                <classname>Zend_CodeGenerator_Php_Docblock_Tab_Return</classname> is an
                annotation tag variant for representing a method return value.
                In this case, the annotation tag name is known ("return"), but
                requires a return type.
            </para>

            <para>
                The class <acronym>API</acronym> is as follows:
            </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> is used to generate
                the full contents of a file that will contain <acronym>PHP</acronym> code. The file
                may contain classes or arbitrary <acronym>PHP</acronym> code, as well as a
                file-level docblock if desired.
            </para>

            <para>
                When adding classes to the file, you will need to pass either an
                array of information to pass to the
                <classname>Zend_CodeGenerator_Php_Class</classname> constructor, or an
                instance of that class. Similarly, with docblocks, you will need
                to pass information for the
                <classname>Zend_CodeGenerator_Php_Docblock</classname> constructor to
                consume or an instance of the class.
            </para>

            <para>
                The <acronym>API</acronym> of the class is as follows:
            </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> is used
                internally by <classname>Zend_CodeGenerator_Php_Class</classname> to keep
                track of class members -- properties and methods alike. These
                are indexed by name, using the concrete instances of the members
                as values.
            </para>

            <para>
                The <acronym>API</acronym> of the class is as follows:
            </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> describes a class
                method, and can generate both the code and the docblock for the
                method. The visibility and status as static,
                abstract, or final may be indicated, per its parent class,
                <classname>Zend_CodeGenerator_Php_Member_Abstract</classname>. Finally,
                the parameters and return value for the method may be specified.
            </para>

            <para>
                Parameters may be set using <methodname>setParameter()</methodname> or
                <methodname>setParameters()</methodname>. In each case, a parameter should
                either be an array of information to pass to the
                <classname>Zend_CodeGenerator_Php_Parameter</classname> constructor or an
                instance of that class.
            </para>

            <para>
                The <acronym>API</acronym> of the class is as follows:
            </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> may be used to
                specify method parameters. Each parameter may have a position
                (if unspecified, the order in which they are registered with the
                method will be used), a default value, and a data type; a
                parameter name is required.
            </para>

            <para>
                The <acronym>API</acronym> of the class is as follows:
            </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>
                There are several problems that might occur when trying to set
                <constant>NULL</constant>, booleans or arrays as default values. For this the value
                holder object <classname>Zend_CodeGenerator_Php_ParameterDefaultValue</classname>
                can be used, for example:
            </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>
                Internally <methodname>setDefaultValue()</methodname> also converts the values
                which can't be expressed in <acronym>PHP</acronym> into the value holder.
            </para>
        </sect3>

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

            <para>
                <classname>Zend_CodeGenerator_Php_Property</classname> describes a class
                property, which may be either a constant or a variable. In each
                case, the property may have an optional default value associated
                with it. Additionally, the visibility of variable properties may
                be set, per the parent class,
                <classname>Zend_CodeGenerator_Php_Member_Abstract</classname>.
            </para>

            <para>
                The <acronym>API</acronym> of the class is as follows:
            </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>