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

<?xml version="1.0" encoding="utf-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.loader.class-map-autoloader">
    <title>The ClassMapAutoloader</title>
    
    <sect2 id="zend.loader.class-map-autoloader.intro">
        <title>Overview</title>

        <para>
            The <classname>ClassMapAutoloader</classname> is designed with performance in mind. The
            idea behind it is simple: when asked to load a class, see if it's in the map, and, if
            so, load the file associated with the class in the map. This avoids unnecessary
            filesystem operations, and can also ensure the autoloader "plays nice" with opcode
            caches and PHP's realpath cache.
        </para>

        <para>
            In order to use the <classname>ClassMapAutoloader</classname>, you first need class
            maps. Zend Framework also provides a tool for generating these class maps; you can find it in
            <filename>bin/classmap_generator.php</filename> of the distribution. Full documentation
            of this too is provided in <xref linkend="zend.loader.classmap-generator"/>.
        </para>
    </sect2>

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

        <para>
            The first step is to generate a class map file. You may run this over any directory
            containing source code anywhere underneath it.
        </para>

        <programlisting language="sh"><![CDATA[
php classmap_generator.php Some/Directory/
]]></programlisting>

        <para>
            This will create a file named <filename>Some/Directory/autoload_classmap.php</filename>, which
            is a PHP file returning an associative array that represents the class map.
        </para>

        <para>
            Within your code, you will now instantiate the
            <classname>ClassMapAutoloader</classname>, and provide it the location of the map.
        </para>

        <programlisting language="php"><![CDATA[
// This example assumes ZF is on your include_path.
// You could also load the autoloader class from a path relative to the
// current script, or via an absolute path.
require_once 'Zend/Loader/ClassMapAutoloader.php';
$loader = new Zend_Loader_ClassMapAutoloader();

// Register the class map:
$loader->registerAutoloadMap('Some/Directory/autoload_classmap.php');

// Register with spl_autoload:
$loader->register();
]]></programlisting>

        <para>
            At this point, you may now use any classes referenced in your class map.
        </para>
    </sect2>

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

        <para>
            The <classname>ClassMapAutoloader</classname> defines the following options.
        </para>

        <variablelist>
            <title>ClassMapAutoloader Options</title>

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

                <listitem>
                    <para>
                        The <classname>ClassMapAutoloader</classname> expects an array of options,
                        where each option is either a filename referencing a class map, or an
                        associative array of class name/filename pairs.
                    </para>

                    <para>
                        As an example:
                    </para>

                    <programlisting language="php"><![CDATA[
// Configuration defining both a file-based class map, and an array map
$config = array(
    __DIR__ . '/library/autoload_classmap.php', // file-based class map
    array(                                      // array class map
        'Application_Bootstrap' => __DIR__ . '/application/Bootstrap.php',
        'Test_Bootstrap'        => __DIR__ . '/tests/Bootstrap.php',
    ),
);
]]></programlisting>
                </listitem>
            </varlistentry>
        </variablelist>
    </sect2>

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

        <refentry id="zend.loader.class-map-autoloader.methods.constructor">
            <refnamediv>
                <refname>__construct</refname>
                <refpurpose>Initialize and configure the object</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>__construct</methodname>
                    <methodparam>
                        <funcparams>$options = null</funcparams>
                    </methodparam>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsection>
                <title>Constructor</title>

                <para>
                    Used during instantiation of the object. Optionally, pass options, which may be
                    either an array or <interfacename>Traversable</interfacename> object; this
                    argument will be passed to <link linkend="zend.loader.class-map-autoloader.methods.set-options">setOptions()</link>.
                </para>
            </refsection>
        </refentry>

        <refentry id="zend.loader.class-map-autoloader.methods.set-options">
            <refnamediv>
                <refname>setOptions</refname>
                <refpurpose>Configure the autoloader</refpurpose>
            </refnamediv>

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

            <refsection>
                <title>setOptions()</title>

                <para>
                    Configures the state of the autoloader, including registering class maps.
                    Expects an array or <interfacename>Traversable</interfacename> object; the
                    argument will be passed to <link linkend="zend.loader.class-map-autoloader.methods.register-autoload-maps">registerAutoloadMaps()</link>.
                </para>
            </refsection>
        </refentry>

        <refentry id="zend.loader.class-map-autoloader.methods.register-autoload-map">
            <refnamediv>
                <refname>registerAutoloadMap</refname>
                <refpurpose>Register a class map</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>registerAutoloadMap</methodname>
                    <methodparam>
                        <funcparams>$map</funcparams>
                    </methodparam>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsection>
                <title>registerAutoloadMap()</title>

                <para>
                    Registers a class map with the autoloader. <varname>$map</varname> may be either
                    a string referencing a PHP script that returns a class map, or an array defining
                    a class map. 
                </para>

                <para>
                    More than one class map may be registered; each will be merged with the
                    previous, meaning it's possible for a later class map to overwrite entries from
                    a previously registered map.
                </para>
            </refsection>
        </refentry>

        <refentry id="zend.loader.class-map-autoloader.methods.register-autoload-maps">
            <refnamediv>
                <refname>registerAutoloadMaps</refname>
                <refpurpose>Register multiple class maps at once</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>registerAutoloadMaps</methodname>
                    <methodparam>
                        <funcparams>$maps</funcparams>
                    </methodparam>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsection>
                <title>registerAutoloadMaps()</title>

                <para>
                    Register multiple class maps with the autoloader. Expects either an array or
                    <interfacename>Traversable</interfacename> object; it then iterates over the
                    argument and passes each value to <link linkend="zend.loader.class-map-autoloader.methods.register-autoload-map">registerAutoloadMap()</link>.
                </para>
            </refsection>
        </refentry>

        <refentry id="zend.loader.class-map-autoloader.methods.get-autoload-map">
            <refnamediv>
                <refname>getAutoloadMap</refname>
                <refpurpose>Retrieve the current class map</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>getAutoloadMap</methodname>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsection>
                <title>getAutoloadMap()</title>

                <para>
                    Retrieves the state of the current class map; the return value is simply an
                    array.
                </para>
            </refsection>
        </refentry>

        <refentry id="zend.loader.class-map-autoloader.methods.autoload">
            <refnamediv>
                <refname>autoload</refname>
                <refpurpose>Attempt to load a class.</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>autoload</methodname>
                    <methodparam>
                        <funcparams>$class</funcparams>
                    </methodparam>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsection>
                <title>autoload()</title>

                <para>
                    Attempts to load the class specified. Returns a boolean
                    <constant>false</constant> on failure, or a string indicating the class loaded
                    on success.
                </para>
            </refsection>
        </refentry>

        <refentry id="zend.loader.class-map-autoloader.methods.register">
            <refnamediv>
                <refname>register</refname>
                <refpurpose>Register with spl_autoload.</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>register</methodname>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsection>
                <title>register()</title>

                <para>
                    Registers the <methodname>autoload()</methodname> method of the current instance
                    with <function>spl_autoload_register()</function>.
                </para>
            </refsection>
        </refentry>
    </sect2>

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

        <example id="zend.loader.class-map-autoloader.examples.configuration">
            <title>Using configuration to seed ClassMapAutoloader</title>

            <para>
                Often, you will want to configure your <classname>ClassMapAutoloader</classname>.
                These values may come from a configuration file, a cache (such as ShMem or
                memcached), or a simple PHP array. The following is an example of a PHP array that
                could be used to configure the autoloader:
            </para>

            <programlisting language="php"><![CDATA[
// Configuration defining both a file-based class map, and an array map
$config = array(
APPLICATION_PATH . '/../library/autoload_classmap.php', // file-based class map
    array(                              // array class map
        'Application_Bootstrap' => APPLICATION_PATH . '/Bootstrap.php',
        'Test_Bootstrap'        => APPLICATION_PATH . '/../tests/Bootstrap.php',
    ),
);
]]></programlisting>
            
            <para>
                An eqivalent INI style configuration might look like this:
            </para>

            <programlisting language="ini"><![CDATA[
classmap.library = APPLICATION_PATH "/../library/autoload_classmap.php"
classmap.resources.Application_Bootstrap = APPLICATION_PATH "/Bootstrap.php"
classmap.resources.Test_Bootstrap = APPLICATION_PATH "/../tests/Bootstrap.php"
]]></programlisting>

            <para>
                Once you have your configuration, you can pass it either to the constructor of the
                <classname>ClassMapAutoloader</classname>, to its
                <methodname>setOptions()</methodname> method, or to
                <methodname>registerAutoloadMaps()</methodname>.
            </para>

            <programlisting language="php"><![CDATA[
/* The following are all equivalent */

// To the constructor:
$loader = new Zend_Loader_ClassMapAutoloader($config);

// To setOptions():
$loader = new Zend_Loader_ClassMapAutoloader();
$loader->setOptions($config);

// To registerAutoloadMaps():
$loader = new Zend_Loader_ClassMapAutoloader();
$loader->registerAutoloadMaps($config);
]]></programlisting>
        </example>
    </sect2>
</sect1>