repo_zf1/documentation/manual/en/module_specs/Zend_Loader-Autoloader.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.loader.autoloader">
    <title>The Autoloader</title>

    <para>
        <classname>Zend_Loader_Autoloader</classname> introduces a comprehensive
        autoloading solution for Zend Framework. It has been designed with
        several goals in mind:
    </para>

    <itemizedlist>
        <listitem>
            <para>
                Provide a true namespace autoloader. (Previous incarnations
                intercepted all userland namespaces.)
            </para>
        </listitem>

        <listitem>
            <para>
                Allow registering arbitrary callbacks as autoloaders, and manage
                them as a stack. (At the time of this writing, this overcomes some
                issues with <code>spl_autoload</code>, which does not allow
                re-registering a callback that utilizes an instance method.)
            </para>
        </listitem>

        <listitem>
            <para>
                Allow optimistic matching of namespaces to provide faster class resolution.
            </para>
        </listitem>
    </itemizedlist>

    <para>
        <classname>Zend_Loader_Autoloader</classname> implements a singleton, making it
        unversally accessible. This provides the ability to register additional
        autoloaders from anywhere in your code as necessary.
    </para>

    <sect2 id="zend.loader.autoloader.usage">
        <title>Using the Autoloader</title>

        <para>
            The first time an instance of the autoloader is retrieved, it
            registers itself with <code>spl_autoload</code>. You retrieve an
            instance using the <methodname>getInstance()</methodname> method:
        </para>

        <programlisting language="php"><![CDATA[
$autoloader = Zend_Loader_Autoloader::getInstance();
]]></programlisting>

        <para>
            By default, the autoloader is configured to match the "Zend_" and
            "ZendX_" namespaces. If you have your own library code that uses
            your own namespace, you may register it with the autoloader using
            the <methodname>registerNamespace()</methodname> method. For instance, if your
            library code is prefixed with "My_", you could do so as follows:
        </para>

        <programlisting language="php"><![CDATA[
$autoloader->registerNamespace('My_');
]]></programlisting>

        <note>
            <title>Namespace Prefixes</title>

            <para>
                You'll note that the previous example uses "My_" and not "My".
                This is because <classname>Zend_Loader_Autoloader</classname> is intended
                as a general purpose autoloader, and does not make the
                assumption that a given class prefix namespace includes an
                underscore. If your class namespace <emphasis>does</emphasis>
                include one, you should include it when registering your
                namespace.
            </para>
        </note>

        <para>
            You can also register arbitrary autoloader callbacks, optionally
            with a specific namespace (or group of namespaces).
            <classname>Zend_Loader_Autoloader</classname> will attempt to match these
            first before using its internal autoloading mechanism.
        </para>

        <para>
            As an example, you may want to utilize one or more eZcomponents
            components with your Zend Framework application. To use its
            autoloading capabilities, push it onto the autoloader stack using
            <methodname>pushAutoloader()</methodname>:
        </para>

        <programlisting language="php"><![CDATA[
$autoloader->pushAutoloader(array('ezcBase', 'autoload'), 'ezc');
]]></programlisting>

        <para>
            This tells the autoloader to use the eZcomponents autoloader for
            classes beginning with "ezc".
        </para>

        <para>
            You can use the <methodname>unshiftAutoloader()</methodname> method to add the
            autoloader to the beginning of the autoloader chain.
        </para>

        <para>
            By default, <classname>Zend_Loader_Autoloader</classname> does no error
            suppression when using its internal autoloader, which utilizes
            <methodname>Zend_Loader::loadClass()</methodname>. Most of the time, this is
            exactly what you want. However, there may be cases where you want to
            suppress them. You can do this using
            <methodname>suppressNotFoundWarnings()</methodname>:
        </para>

        <programlisting language="php"><![CDATA[
$autoloader->suppressNotFoundWarnings(true);
]]></programlisting>

        <para>
            Finally, there may be times when you want the autoloader to load any
            namespace. For instance, PEAR libraries do not share a common
            namespace, making specifying individual namespaces difficult when
            many PEAR components are in use. You can use the
            <methodname>setFallbackAutoloader()</methodname> method to have the autoloader
            act as a catch-all:
        </para>

        <programlisting language="php"><![CDATA[
$autoloader->setFallbackAutoloader(true);
]]></programlisting>

        <note>
            <title>Loading Classes from PHP Namespaces</title>

            <para>
                Starting in version 1.10.0, Zend Framework now allows loading classes from
                <acronym>PHP</acronym> namespaces. This support follows the same guidelines and
                implementation as that found in the <ulink
                    url="http://groups.google.com/group/php-standards/web/psr-0-final-proposal">PHP
                Framework Interop Group PSR-0</ulink> reference implementation.
            </para>

            <para>
                Under this guideline, the following rules apply:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        Each namespace separator is converted to a
                        <constant>DIRECTORY_SEPARATOR</constant> when loading from the file system.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Each "_" character in the <emphasis>CLASS NAME</emphasis> is converted to a
                        <constant>DIRECTORY_SEPARATOR</constant>. The "_" character has no special
                        meaning in the namespace.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        The fully-qualified namespace and class is suffixed with ".php" when loading
                        from the file system.
                    </para>
                </listitem>
            </itemizedlist>

            <para>
                As examples:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <classname>\Doctrine\Common\IsolatedClassLoader</classname> =&gt;
                        <filename>/path/to/project/lib/vendor/Doctrine/Common/IsolatedClassLoader.php</filename>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <classname>\namespace\package\Class_Name</classname> =&gt;
                        <filename>/path/to/project/lib/vendor/namespace/package/Class/Name.php</filename>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <classname>\namespace\package_name\Class_Name</classname> =&gt;
                        <filename>/path/to/project/lib/vendor/namespace/package_name/Class/Name.php</filename>
                    </para>
                </listitem>
            </itemizedlist>
        </note>
    </sect2>

    <sect2 id="zend.loader.autoloader.zf-version">
        <title>Selecting a Zend Framework version</title>

        <para>
            Typically, you will use the version of Zend Framework that the autoloader you
            instantiate came with. However, when developing a project, it's often useful to track
            specific versions, major or minor branches, or just the latest version.
            <classname>Zend_Loader_Autoloader</classname>, as of version 1.10, offers some features
            to help manage this task.
        </para>

        <para>
            Imagine the following scenario:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    During <emphasis>development</emphasis>, you want to track the latest version of
                    Zend Framework you have installed, so that you can ensure the application works
                    when you upgrade between versions.
                </para>

                <para>
                    When pushing to <emphasis>Quality Assurance</emphasis>, however, you need to
                    have slightly more stability, so you want to use the latest installed revision
                    of a specific minor version.
                </para>

                <para>
                    Finally, when you push to <emphasis>production</emphasis>, you want to pin to a
                    specific installed version, to ensure no breakage occurs if or when you add new
                    versions of Zend Framework to you server.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            The autoloader allows you to do this with the method
            <methodname>setZfPath()</methodname>. This method takes two arguments, a
            <emphasis>path</emphasis> to a set of Zend Framework installations, and a
            <emphasis>version</emphasis> to use. Once invoked, it prepends a path to the
            <constant>include_path</constant> pointing to the appropriate Zend Framework
            installation library.
        </para>

        <para>
            The directory you specify as your <emphasis>path</emphasis> should have a tree such as
            the following:
        </para>

        <programlisting language="text"><![CDATA[
ZendFramework/
|-- 1.9.2/
|   |-- library/
|-- ZendFramework-1.9.1-minimal/
|   |-- library/
|-- 1.8.4PL1/
|   |-- library/
|-- 1.8.4/
|   |-- library/
|-- ZendFramework-1.8.3/
|   |-- library/
|-- 1.7.8/
|   |-- library/
|-- 1.7.7/
|   |-- library/
|-- 1.7.6/
|   |-- library/
]]></programlisting>

        <para>
            (where <emphasis>path</emphasis> points to the directory "ZendFramework" in the above
            example)
        </para>

        <para>
            Note that each subdirectory should contain the directory <filename>library</filename>,
            which contains the actual Zend Framework library code. The individual subdirectory names
            may be version numbers, or simply be the untarred contents of a standard Zend Framework
            distribution tarball/zipfile.
        </para>

        <para>
            Now, let's address the use cases. In the first use case, in
            <emphasis>development</emphasis>, we want to track the latest source install. We can do
            that by passing "latest" as the version:
        </para>

        <programlisting language="php"><![CDATA[
$autoloader->setZfPath($path, 'latest');
]]></programlisting>

        <para>
            In the example from above, this will map to the directory
            <filename>ZendFramework/1.9.2/library/</filename>; you can verify this by checking the
            return value of <methodname>getZfPath()</methodname>.
        </para>

        <para>
            In the second situation, for <emphasis>quality assurance</emphasis>, let's say we want
            to pin to the 1.8 minor release, using the latest install you have for that release. You
            can do so as follows:
        </para>

        <programlisting language="php"><![CDATA[
$autoloader->setZfPath($path, '1.8');
]]></programlisting>

        <para>
            In this case, it will find the directory
            <filename>ZendFramework/1.8.4PL1/library/</filename>.
        </para>

        <para>
            In the final case, for <emphasis>production</emphasis>, we'll pin to a specific version
            -- 1.7.7, since that was what was available when Quality Assurance tested prior to our
            release.
        </para>

        <programlisting language="php"><![CDATA[
$autoloader->setZfPath($path, '1.7.7');
]]></programlisting>

        <para>
            Predictably, it finds the directory <filename>ZendFramework/1.7.7/library/</filename>.
        </para>

        <para>
            You can also specify these values in the configuration file you use with
            <filename>Zend_Application</filename>. To do so, you'd specify the following
            information:
        </para>

        <programlisting language="ini"><![CDATA[
[production]
autoloaderZfPath = "path/to/ZendFramework"
autoloaderZfVersion = "1.7.7"

[qa]
autoloaderZfVersion = "1.8"

[development]
autoloaderZfVersion = "latest"
]]></programlisting>

        <para>
            Note the different environment sections, and the different version specified in each
            environment; these factors will allow <classname>Zend_Application</classname> to
            configure the autoloader appropriately.
        </para>

        <warning>
            <title>Performance implications</title>

            <para>
                For best performance, either do not use this feature, or specify a specific Zend
                Framework version (i.e., not "latest", a major revision such as "1", or a minor
                revision such as "1.8"). Otherwise, the autoloader will need to scan the provided
                path for directories matching the criteria -- a somewhat expensive operation to
                perform on each request.
            </para>
        </warning>
    </sect2>

    <sect2 id="zend.loader.autoloader.interface">
        <title>The Autoloader Interface</title>

        <para>
            Besides being able to specify arbitrary callbacks as autoloaders,
            Zend Framework also defines an interface autoloading classes may
            imlement, <classname>Zend_Loader_Autoloader_Interface</classname>:
        </para>

        <programlisting language="php"><![CDATA[
interface Zend_Loader_Autoloader_Interface
{
    public function autoload($class);
}
]]></programlisting>

        <para>
            When using this interface, you can simply pass a class instance to
            <classname>Zend_Loader_Autoloader</classname>'s
            <methodname>pushAutoloader()</methodname>
            and <methodname>unshiftAutoloader()</methodname> methods:
        </para>

        <programlisting language="php"><![CDATA[
// Assume Foo_Autoloader implements Zend_Loader_Autoloader_Interface:
$foo = new Foo_Autoloader();

$autoloader->pushAutoloader($foo, 'Foo_');
]]></programlisting>
    </sect2>

    <sect2 id="zend.loader.autoloader.reference">
        <title>Autoloader Reference</title>

        <para>
            Below, please find a guide to the methods available in
            <classname>Zend_Loader_Autoloader</classname>.
        </para>

        <table id="zend.loader.autoloader.reference.api">
            <title>Zend_Loader_Autoloader Methods</title>

            <tgroup cols="4">
                <thead>
                    <row>
                        <entry>Method</entry>
                        <entry>Return Value</entry>
                        <entry>Parameters</entry>
                        <entry>Description</entry>
                    </row>
                </thead>

                <tbody>
                    <row>
                        <entry><methodname>getInstance()</methodname></entry>
                        <entry><classname>Zend_Loader_Autoloader</classname></entry>
                        <entry>N/A</entry>

                        <entry>
                            <para>
                                Retrieve the <classname>Zend_Loader_Autoloader</classname>
                                singleton instance. On first retrieval, it registers
                                itself with <code>spl_autoload</code>. This method is static.
                            </para>
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>resetInstance()</methodname></entry>
                        <entry><code>void</code></entry>
                        <entry>N/A</entry>

                        <entry>
                            <para>
                                Resets the state of the
                                <classname>Zend_Loader_Autoloader</classname> singleton instance to
                                it's original state, unregistering all autoloader callbacks and all
                                registered namespaces.
                            </para>
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>autoload($class)</methodname></entry>
                        <entry><code>string|<constant>FALSE</constant></code></entry>

                        <entry>
                            <itemizedlist>
                                <listitem>
                                    <para>
                                        <varname>$class</varname>, <emphasis>required</emphasis>.
                                        A string class name to load.
                                    </para>
                                </listitem>
                            </itemizedlist>
                        </entry>

                        <entry>
                            <para>Attempt to resolve a class name to a file and load it.</para>
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>setDefaultAutoloader($callback)</methodname></entry>
                        <entry><classname>Zend_Loader_Autoloader</classname></entry>

                        <entry>
                            <itemizedlist>
                                <listitem>
                                    <para>
                                        <varname>$callback</varname>, <emphasis>required</emphasis>.
                                    </para>
                                </listitem>
                            </itemizedlist>
                        </entry>

                        <entry>
                            <para>
                                Specify an alternate <acronym>PHP</acronym> callback to use for the
                                default autoloader implementation.
                            </para>
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>getDefaultAutoloader()</methodname></entry>
                        <entry><code>callback</code></entry>
                        <entry>N/A</entry>

                        <entry>
                            <para>
                                Retrieve the default autoloader implementation; by default, this is
                                <methodname>Zend_Loader::loadClass()</methodname>.
                            </para>
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>setAutoloaders(array $autoloaders)</methodname></entry>
                        <entry><classname>Zend_Loader_Autoloader</classname></entry>

                        <entry>
                            <itemizedlist>
                                <listitem>
                                    <para>
                                        <varname>$autoloaders</varname>,
                                        <emphasis>required</emphasis>.
                                    </para>
                                </listitem>
                            </itemizedlist>
                        </entry>

                        <entry>
                            <para>
                                Set a list of concrete autoloaders to use in the
                                autoloader stack. Each item in the autoloaders array
                                must be a <acronym>PHP</acronym> callback.
                            </para>
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>getAutoloaders()</methodname></entry>
                        <entry><type>Array</type></entry>
                        <entry>N/A</entry>
                        <entry><para>Retrieve the internal autoloader stack.</para></entry>
                    </row>

                    <row>
                        <entry><methodname>getNamespaceAutoloaders($namespace)</methodname></entry>
                        <entry><type>Array</type></entry>

                        <entry>
                            <itemizedlist>
                                <listitem>
                                    <para>
                                        <varname>$namespace</varname>, <emphasis>required</emphasis>
                                    </para>
                                </listitem>
                            </itemizedlist>
                        </entry>

                        <entry>
                            <para>
                                Fetch all autoloaders that have registered to load a
                                specific namespace.
                            </para>
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>registerNamespace($namespace)</methodname></entry>
                        <entry><classname>Zend_Loader_Autoloader</classname></entry>

                        <entry>
                            <itemizedlist>
                                <listitem>
                                    <para>
                                        <varname>$namespace</varname>,
                                        <emphasis>required</emphasis>.
                                    </para>
                                </listitem>
                            </itemizedlist>
                        </entry>

                        <entry>
                            <para>
                                Register one or more namespaces with the default
                                autoloader. If <varname>$namespace</varname> is a string,
                                it registers that namespace; if it's an array of
                                strings, registers each as a namespace.
                            </para>
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>unregisterNamespace($namespace)</methodname></entry>
                        <entry><classname>Zend_Loader_Autoloader</classname></entry>

                        <entry>
                            <itemizedlist>
                                <listitem>
                                    <para>
                                        <varname>$namespace</varname>,
                                        <emphasis>required</emphasis>.
                                    </para>
                                </listitem>
                            </itemizedlist>
                        </entry>

                        <entry>
                            <para>
                                Unregister one or more namespaces from the default
                                autoloader. If <varname>$namespace</varname> is a string,
                                it unregisters that namespace; if it's an array of
                                strings, unregisters each as a namespace.
                            </para>
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>getRegisteredNamespaces()</methodname></entry>
                        <entry><type>Array</type></entry>
                        <entry>N/A</entry>

                        <entry>
                            <para>
                                Returns an array of all namespaces registered with the default
                                autoloader.
                            </para>
                        </entry>
                    </row>

                    <row>
                        <entry>
                            <methodname>suppressNotFoundWarnings($flag = null)</methodname>
                        </entry>

                        <entry><code>boolean|Zend_Loader_Autoloader</code></entry>

                        <entry>
                            <itemizedlist>
                                <listitem>
                                    <para>
                                        <varname>$flag</varname>, <emphasis>optional</emphasis>.
                                    </para>
                                </listitem>
                            </itemizedlist>
                        </entry>

                        <entry>
                            <para>
                                Set or retrieve the value of the flag used to
                                indicate whether the default autoloader
                                implementation should suppress "file not found"
                                warnings. If no arguments or a <constant>NULL</constant> value is
                                passed, returns a boolean indicating the status of the flag;
                                if a boolean is passed, the flag is set to that
                                value and the autoloader instance is returned (to
                                allow method chaining).
                            </para>
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>setFallbackAutoloader($flag)</methodname></entry>
                        <entry><classname>Zend_Loader_Autoloader</classname></entry>

                        <entry>
                            <itemizedlist>
                                <listitem>
                                    <para>
                                        <varname>$flag</varname>, <emphasis>required</emphasis>.
                                    </para>
                                </listitem>
                            </itemizedlist>
                        </entry>

                        <entry>
                            <para>
                                Set the value of the flag used to indicate whether
                                or not the default autoloader should be used as a
                                fallback or catch-all autoloader for all namespaces.
                            </para>
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>isFallbackAutoloader()</methodname></entry>
                        <entry><type>Boolean</type></entry>
                        <entry>N/A</entry>
                        <entry>
                            <para>
                                Retrieve the value of the flag used to indicate whether
                                or not the default autoloader should be used as a
                                fallback or catch-all autoloader for all namespaces.
                                By default, this is <constant>FALSE</constant>.
                            </para>
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>getClassAutoloaders($class)</methodname></entry>
                        <entry><type>Array</type></entry>

                        <entry>
                            <itemizedlist>
                                <listitem>
                                    <para>
                                        <varname>$class</varname>, <emphasis>required</emphasis>.
                                    </para>
                                </listitem>
                            </itemizedlist>
                        </entry>

                        <entry>
                            <para>
                                Get the list of namespaced autoloaders that could
                                potentially match the provided class. If none match,
                                all global (non-namespaced) autoloaders are returned.
                            </para>
                        </entry>
                    </row>

                    <row>
                        <entry>
                            <methodname>unshiftAutoloader($callback, $namespace = '')</methodname>
                        </entry>

                        <entry><classname>Zend_Loader_Autoloader</classname></entry>

                        <entry>
                            <itemizedlist>
                                <listitem>
                                    <para>
                                        <varname>$callback</varname>, <emphasis>required</emphasis>.
                                        A valid <acronym>PHP</acronym> callback
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        <varname>$namespace</varname>,
                                        <emphasis>optional</emphasis>. A string representing a class
                                        prefix namespace.
                                    </para>
                                </listitem>
                            </itemizedlist>
                        </entry>

                        <entry>
                            <para>
                                Add a concrete autoloader implementation to the
                                beginning of the internal autoloader stack. If a
                                namespace is provided, that namespace will be used
                                to match optimistically; otherwise, the autoloader
                                will be considered a global autoloader.
                            </para>
                        </entry>
                    </row>

                    <row>
                        <entry>
                            <methodname>pushAutoloader($callback, $namespace = '')</methodname>
                        </entry>
                        <entry><classname>Zend_Loader_Autoloader</classname></entry>

                        <entry>
                            <itemizedlist>
                                <listitem>
                                    <para>
                                        <varname>$callback</varname>, <emphasis>required</emphasis>.
                                        A valid <acronym>PHP</acronym> callback
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        <varname>$namespace</varname>,
                                        <emphasis>optional</emphasis>. A string representing a class
                                        prefix namespace.
                                    </para>
                                </listitem>
                            </itemizedlist>
                        </entry>

                        <entry>
                            <para>
                                Add a concrete autoloader implementation to the
                                end of the internal autoloader stack. If a
                                namespace is provided, that namespace will be used
                                to match optimistically; otherwise, the autoloader
                                will be considered a global autoloader.
                            </para>
                        </entry>
                    </row>

                    <row>
                        <entry>
                            <methodname>removeAutoloader($callback, $namespace = '')</methodname>
                        </entry>

                        <entry><classname>Zend_Loader_Autoloader</classname></entry>

                        <entry>
                            <itemizedlist>
                                <listitem>
                                    <para>
                                        <varname>$callback</varname>, <emphasis>required</emphasis>.
                                        A valid <acronym>PHP</acronym> callback
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        <varname>$namespace</varname>,
                                        <emphasis>optional</emphasis>. A string representing a class
                                        prefix namespace, or an array of namespace strings.
                                    </para>
                                </listitem>
                            </itemizedlist>
                        </entry>

                        <entry>
                            <para>
                                Remove a concrete autoloader implementation from
                                the internal autoloader stack. If a namespace or
                                namespaces are provided, the callback will be
                                removed from that namespace or namespaces only.
                            </para>
                        </entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
    </sect2>
</sect1>