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

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

    <para>
        The various classes in <classname>Zend_Reflection</classname> mimic the
        <acronym>API</acronym> of <acronym>PHP</acronym>'s <ulink
            url="http://php.net/reflection">Reflection <acronym>API</acronym></ulink> - with one
        important difference. <acronym>PHP</acronym>'s Reflection <acronym>API</acronym> does not
        provide introspection into docblock annotation tags, nor into parameter variable
        types or return types.
    </para>

    <para>
        <classname>Zend_Reflection</classname> analyzes method docblock annotations to
        determine parameter variable types and the return type. Specifically,
        the <code>@param</code> and <code>@return</code> annotations are used.
        However, you can also check for any other annotation tags, as well as
        the standard "short" and "long" descriptions.
    </para>

    <para>
        Each reflection object in <classname>Zend_Reflection</classname> overrides the
        <methodname>getDocblock()</methodname> method to return an instance of
        <classname>Zend_Reflection_Docblock</classname>. This class provides introspection
        into the docblocks and annotation tags.
    </para>

    <para>
        <classname>Zend_Reflection_File</classname> is a new reflection class that allows
        introspection of <acronym>PHP</acronym> files. With it, you can retrieve the classes,
        functions, and global <acronym>PHP</acronym> code contained in the file.
    </para>

    <para>
        Finally, the various methods that return other reflection objects
        allow a second parameter, the name of the reflection class to use for
        the returned reflection object.
    </para>

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

        <para>
            <classname>Zend_Reflection_Docblock</classname> is the heart of
            <classname>Zend_Reflection</classname>'s value-add over <acronym>PHP</acronym>'s
            Reflection <acronym>API</acronym>. It provides the following methods:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>getContents()</methodname>: returns the full contents of the
                    docblock.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getStartLine()</methodname>: returns the starting position of
                    the docblock within the defining file.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getEndLine()</methodname>: get last line of docblock within the
                    defining file.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getShortDescription()</methodname>: get the short, one-line
                    description (usually the first line of the docblock).
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getLongDescription()</methodname>: get the long description from
                    the docblock.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>hasTag($name)</methodname>: determine if the docblock has the
                    given annotation tag.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getTag($name)</methodname>: Retrieve the given annotation tag
                    reflection object, or a boolean <constant>FALSE</constant> if it's not
                    present.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getTags($filter)</methodname>: Retrieve all tags, or all tags
                    matching the given <varname>$filter</varname> string. The tags
                    returned will be an array of
                    <classname>Zend_Reflection_Docblock_Tag</classname> objects.
                </para>
            </listitem>
        </itemizedlist>
    </sect2>

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

        <para>
            <classname>Zend_Reflection_Docblock_Tag</classname> provides reflection for
            individual annotation tags. Most tags consist of only a name and a
            description. In the case of some special tags, the class provides a
            factory method for retrieving an instance of the appropriate class.
        </para>

        <para>
            The following methods are defined for
            <classname>Zend_Reflection_Docblock_Tag</classname>:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>factory($tagDocblockLine)</methodname>: instantiate the
                    appropriate tag reflection class and return it.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getName()</methodname>: return the annotation tag name.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getDescription()</methodname>: return the annotation
                    description.
                </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> is a specialized
            version of <classname>Zend_Reflection_Docblock_Tag</classname>. The
            <code>@param</code> annotation tag description consists of the
            parameter type, variable name, and variable description. It adds the
            following methods to <classname>Zend_Reflection_Docblock_Tag</classname>:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>getType()</methodname>: return the parameter variable type.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getVariableName()</methodname>: return the parameter variable
                    name.
                </para>
            </listitem>
        </itemizedlist>
    </sect2>

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

        <para>
            Like <classname>Zend_Reflection_Docblock_Tag_Param</classname>,
            <classname>Zend_Reflection_Docblock_Tag_Return</classname> is a specialized
            version of <classname>Zend_Reflection_Docblock_Tag</classname>. The
            <code>@return</code> annotation tag description consists of the
            return type and variable description. It adds the following method
            to <classname>Zend_Reflection_Docblock_Tag</classname>:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>getType()</methodname>: return the return type.
                </para>
            </listitem>
        </itemizedlist>
    </sect2>

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

        <para>
            <classname>Zend_Reflection_File</classname> provides introspection into
            <acronym>PHP</acronym> files. With it, you can introspect the classes, functions, and
            bare <acronym>PHP</acronym> code defined in a file. It defines the following methods:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>getFileName()</methodname>: retrieve the filename of the file
                    being reflected.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getStartLine()</methodname>: retrieve the starting line of the
                    file (always "1").
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getEndLine()</methodname> retrieve the last line / number of
                    lines in the file.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>getDocComment($reflectionClass =
                        'Zend_Reflection_Docblock')</code>: retrive the file-level
                    docblock reflection object.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>getClasses($reflectionClass =
                        'Zend_Reflection_Class')</code>: retrieve an array of
                    reflection objects, one for each class defined in the file.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>getFunctions($reflectionClass =
                        'Zend_Reflection_Function')</code>: retrieve an array of
                    reflection objects, one for each function defined in the file.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>getClass($name = null, $reflectionClass =
                        'Zend_Reflection_Class')</code>: retrieve the reflection
                    object for a single class.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getContents()</methodname>: retrieve the full contents of the
                    file.
                </para>
            </listitem>
        </itemizedlist>
    </sect2>

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

        <para>
            <classname>Zend_Reflection_Class</classname> extends
            <code>ReflectionClass</code>, and follows its <acronym>API</acronym>. It adds one
            additional method, <methodname>getDeclaringFile()</methodname>, which may be
            used to retrieve the <classname>Zend_Reflection_File</classname> reflection
            object for the defining file.
        </para>

        <para>
            Additionally, the following methods add an additional argument for
            specifying the reflection class to use when fetching a reflection
            object:
        </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>
                    <methodname>getMethods($filter = -1, $reflectionClass =
                        'Zend_Reflection_Method')</methodname>
                </para>
            </listitem>

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

            <listitem>
                <para>
                    <code>getProperty($name, $reflectionClass = 'Zend_Reflection_Property')</code>
                </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> extends
            <code>ReflectionExtension</code>, and follows its <acronym>API</acronym>. It overrides
            the following methods to add an additional argument for specifying
            the reflection class to use when fetching a reflection object:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>getFunctions($reflectionClass =
                        'Zend_Reflection_Function')</code>: retrieve an array of
                    reflection objects representing the functions defined by the extension.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>getClasses($reflectionClass =
                        'Zend_Reflection_Class')</code>: retrieve an array of
                    reflection objects representing the classes defined by the extension.
                </para>
            </listitem>
        </itemizedlist>
    </sect2>

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

        <para>
            <classname>Zend_Reflection_Function</classname> adds a method for retrieving
            the function return type, as well as overrides several methods to
            allow specifying the reflection class to use for returned reflection
            objects.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>getDocblock($reflectionClass =
                        'Zend_Reflection_Docblock')</code>: retrieve the function
                    docblock reflection object.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>getParameters($reflectionClass =
                        'Zend_Reflection_Parameter')</code>: retrieve an array of
                    all function parameter reflection objects.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getReturn()</methodname>: retrieve the return type reflection
                    object.
                </para>
            </listitem>
        </itemizedlist>
    </sect2>

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

        <para>
            <classname>Zend_Reflection_Method</classname> mirrors
            <classname>Zend_Reflection_Function</classname>, and only overrides one
            additional method:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>getParentClass($reflectionClass =
                        'Zend_Reflection_Class')</code>: retrieve the parent class
                    reflection object.
                </para>
            </listitem>
        </itemizedlist>
    </sect2>

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

        <para>
            <classname>Zend_Reflection_Parameter</classname> adds a method for retrieving
            the parameter type, as well as overrides methods to allow specifying
            the reflection class to use on returned reflection objects.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>getDeclaringClass($reflectionClass =
                        'Zend_Reflection_Class')</code>: get the declaring class of
                    the parameter as a reflection object (if available).
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>getClass($reflectionClass =
                        'Zend_Reflection_Class')</code>: get the class of
                    the parameter as a reflection object (if available).
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>getDeclaringFunction($reflectionClass =
                        'Zend_Reflection_Function')</code>: get the function of
                    the parameter as a reflection object (if available).
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getType()</methodname>: get the parameter type.
                </para>
            </listitem>
        </itemizedlist>
    </sect2>

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

        <para>
            <classname>Zend_Reflection_Property</classname> overrides a single method in
            order to allow specifying the returned reflection object class:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>getDeclaringClass($reflectionClass =
                        'Zend_Reflection_Class')</code>: retrieve the declaring
                    class of the property as a reflection object.
                </para>
            </listitem>
        </itemizedlist>
    </sect2>
</sect1>