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

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

    <sect2 id="zend.loader.autoloader-factory.intro">
        <title>Overview</title>

        <para>
            Starting with version 1.12.0, Zend Framework now offers multiple autoloader strategies.
            Often, it will be useful to employ multiple autoloading strategies; as an example, you
            may have a class map for your most used classes, but want to use a PSR-0 style
            autoloader for 3rd party libraries.
        </para>

        <para>
            While you could potentially manually configure these, it may be more useful to define
            the autoloader configuration somewhere and cache it. For these cases, the
            <classname>AutoloaderFactory</classname> will be useful.
        </para>
    </sect2>

    <sect2 id="zend.loader.autoloader-factory.quick-start">
        <title>Quick Start</title>

        <para>
            Configuration may be stored as a PHP array, or in some form of configuration file. As an
            example, consider the following PHP array:
        </para>

        <programlisting language="php"><![CDATA[
$config = array(
    'Zend_Loader_ClassMapAutoloader' => array(
        'application' => APPLICATION_PATH . '/autoload_classmap.php',
        'zf'          => APPLICATION_PATH . '/../library/Zend/autoload_classmap.php',
    ),
    'Zend_Loader_StandardAutoloader' => array(
        'namespaces' => array(
            'Phly\Mustache' => APPLICATION_PATH . '/../library/Phly/Mustache',
            'Doctrine'      => APPLICATION_PATH . '/../library/Doctrine',
        ),
    ),
);
]]></programlisting>

        <para>
            An equivalent INI-style configuration might look like the following:
        </para>

        <programlisting xml:lang="ini"><![CDATA[
Zend_Loader_ClassMapAutoloader.application = APPLICATION_PATH "/autoload_classmap.php"
Zend_Loader_ClassMapAutoloader.zf          = APPLICATION_PATH "/../library/Zend/autoload_classmap.php"
Zend_Loader_StandardAutoloader.namespaces.Phly\Mustache = APPLICATION_PATH "/../library/Phly/Mustache"
Zend_Loader_StandardAutoloader.namespaces.Doctrine       = APPLICATION_PATH "/../library/Doctrine"
]]></programlisting>

        <para>
            Once you have your configuration in a PHP array, you simply pass it to the
            <classname>AutoloaderFactory</classname>.
        </para>

        <programlisting language="php"><![CDATA[
// This example assumes ZF is on your include_path.
// You could also load the factory class from a path relative to the
// current script, or via an absolute path.
require_once 'Zend_Loader_AutoloaderFactory.php';
Zend_Loader_AutoloaderFactory::factory($config);
]]></programlisting>

        <para>
            The <classname>AutoloaderFactory</classname> will instantiate each autoloader with the
            given options, and also call its <methodname>register()</methodname> method to register
            it with the SPL autoloader.
        </para>
    </sect2>

    <sect2 id="zend.loader.autoloader-factory.options">
        <title>Configuration Options</title>

        <variablelist>
            <title>AutoloaderFactory Options</title>

            <varlistentry>
                <term>$options</term>

                <listitem>
                    <para>
                        The <classname>AutoloaderFactory</classname> expects an associative array or
                        <interfacename>Traversable</interfacename> object. Keys should be valid
                        autoloader class names, and the values should be the options that should be
                        passed to the class constructor.
                    </para>

                    <para>
                        Internally, the <classname>AutoloaderFactory</classname> checks to see if
                        the autoloader class referenced exists. If not, it will use the <link linkend="zend.loader.standard-autoloader">StandardAutoloader</link> to
                        attempt to load the class via the <varname>include_path</varname> (or, in
                        the case of "Zend"-namespaced classes, using the Zend Framework library
                        path). If the class is not found, or does not implement the
                        <link linkend="zend.loader.spl-autoloader">SplAutoloader</link> interface,
                        an exception will be raised.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </sect2>

    <sect2 id="zend.loader.autoloader-factory.methods">
        <title>Available Methods</title>

        <refentry id="zend.loader.autoloader-factory.methods.factory">
            <refnamediv>
                <refname>factory</refname>
                <refpurpose>Instantiate and register autoloaders</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>factory</methodname>
                    <methodparam>
                        <funcparams>$options</funcparams>
                    </methodparam>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsection>
                <title>factory()</title>

                <para>
                    This method is <emphasis>static</emphasis>, and is used to instantiate
                    autoloaders and register them with the SPL autoloader. It expects either an
                    array or <interfacename>Traversable</interfacename> object as denoted in the
                    <link linkend="zend.loader.autoloader-factory.options">Options section</link>.
                </para>
            </refsection>
        </refentry>

        <refentry id="zend.loader.autoloader-factory.methods.get-registered-autoloaders">
            <refnamediv>
                <refname>getRegisteredAutoloaders</refname>
                <refpurpose>Retrieve a list of all autoloaders registered using the factory</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>getRegisteredAutoloaders</methodname>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsection>
                <title>getRegisteredAutoloaders()</title>

                <para>
                    This method is <emphasis>static</emphasis>, and may be used to retrieve a list
                    of all autoloaders registered via the <methodname>factory()</methodname> method.
                    It returns simply an array of autoloader instances.
                </para>
            </refsection>
        </refentry>
    </sect2>

    <sect2 id="zend.loader.autoloader-factory.examples">
        <title>Examples</title>

        <para>
            Please see the <link linkend="zend.loader.autoloader-factory.quick-start">Quick
                Start</link> for a detailed example.
        </para>
    </sect2>
</sect1>