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

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

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

        <para>
            <classname>Zend_Loader_StandardAutoloader</classname> is designed as a <ulink
                url="http://groups.google.com/group/php-standards/web/psr-0-final-proposal">PSR-0</ulink>-compliant
            autoloader. It assumes a 1:1 mapping of the namespace+classname to the filesystem,
            wherein namespace separators and underscores are translated to directory separators. A
            simple statement that illustrates how resolution works is as follows:
        </para>

        <programlisting language="php"><![CDATA[
$filename = str_replace(array('_', '\\'), DIRECTORY_SEPARATOR, $classname) 
          . '.php';
]]></programlisting>

        <para>
            Previous incarnations of PSR-0-compliant autoloaders in Zend Framework have relied upon
            the <varname>include_path</varname> for file lookups. This has led to a number of
            issues:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    Due to the use of <function>include</function>, if the file is not
                    found, a warning is raised -- even if another autoloader is capable of resolving
                    the class later.
                </para>
            </listitem>

            <listitem>
                <para>
                    Documenting how to setup the <varname>include_path</varname> has proven to be
                    a difficult concept to convey.
                </para>
            </listitem>

            <listitem>
                <para>
                    If multiple Zend Framework installations exist on the
                    <varname>include_path</varname>, the first one on the path wins -- even if that
                    was not the one the developer intended.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            To solve these problems, the <classname>StandardAutoloader</classname> by default
            requires that you explicitly register namespace/path pairs (or vendor prefix/path
            pairs), and will only load a file if it exists within the given path. Multiple pairs may
            be provided.
        </para>

        <para>
            As a measure of last resort, you may also use the
            <classname>StandardAutoloader</classname> as a "fallback" autoloader -- one that will
            look for classes of any namespace or vendor prefix on the
            <classname>include_path</classname>. This practice is not recommended, however, due to
            performance implications.
        </para>

        <para>
            Finally, as with all autoloaders in Zend Framework, the
            <classname>StandardAutoloader</classname> is capable of registering itself with PHP's
            SPL autoloader registry.
        </para>

        <note>
            <title>Vocabulary: Namespaces vs. Vendor Prefixes</title>
            

            <para>
                In terms of autloading, a "namespace" corresponds to PHP's own definition of
                namespaces in PHP versions 5.3 and above.
            </para>

            <para>
                A "vendor prefix" refers to the practice, popularized in PHP versions prior to 5.3,
                of providing a pseudo-namespace in the form of underscore-separated words in class
                names. As an example, the class <classname>Phly_Couch_Document</classname> uses a
                vendor prefix of "Phly", and a component prefix of "Phly_Couch" -- but it is a class
                sitting in the global namespace within PHP 5.3.
            </para>

            <para>
                The <classname>StandardAutoloader</classname> is capable of loading either
                namespaced or vendor prefixed class names, but treats them separately when
                attempting to match them to an appropriate path.
            </para>
        </note>
    </sect2>

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

        <para>
            Basic use of the <classname>StandardAutoloader</classname> requires simply registering
            namespace/path pairs. This can either be done at instantiation, or via explicit method
            calls after the object has been initialized. Calling <methodname>register()</methodname>
            will register the autoloader with the SPL autoloader registry.
        </para>

        <para>
            By default, the class will register the "Zend" namespace to the directory above where
            its own classfile is located on the filesystem.
        </para>

        <example id="zend.loader.standard-autoloader.quick-start.example-manual-configuration">
            <title>Manual Configuration</title>
            
            <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/StandardAutoloader.php';
$loader = new Zend_Loader_StandardAutoloader();

// Register the "Phly" namespace:
$loader->registerNamespace('Phly', APPLICATION_PATH . '/../library/Phly');

// Register the "Scapi" vendor prefix:
$loader->registerPrefix('Scapi', APPLICATION_PATH . '/../library/Scapi');

// Optionally, specify the autoloader as a "fallback" autoloader;
// this is not recommended.
$loader->setFallbackAutoloader(true);

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

        <example id="zend.loader.standard-autoloader.quick-start.example-constructor-configuration">
            <title>Configuration at Instantiation</title>

            <para>
                The <classname>StandardAutoloader</classname> may also be configured at
                instantiation. Please note:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        The argument passed may be either an array or a
                        <interface>Traversable</interface> object (such as a
                        <classname>Zend_Config</classname> object.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        The argument passed is also a valid argument for passing to the
                        <methodname>setOptions()</methodname> method.
                    </para>
                </listitem>
            </itemizedlist>

            <para>
                The following is equivalent to the previous example.
            </para>

            <programlisting language="php"><![CDATA[
require_once 'Zend/Loader/StandardAutoloader.php';
$loader = new Zend_Loader_StandardAutoloader(array(
    'namespaces' => array(
        'Phly' => APPLICATION_PATH . '/../library/Phly',
    ),
    'prefixes' => array(
        'Scapi' => APPLICATION_PATH . '/../library/Scapi',
    ),
    'fallback_autoloader' => true,
));

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

    <sect2 id="zend.loader.standard-autoloader.options">
        <title>Configuration Options</title>
        
        <para>
            The <classname>StandardAutoloader</classname> defines the following options.
        </para>

        <variablelist>
            <title>StandardAutoloader Options</title>
            

            <varlistentry>
                <term>namespaces</term>

                <listitem>
                    <para>
                        An associative array of namespace/path pairs. The path should be an absolute
                        path or path relative to the calling script, and contain only classes that
                        live in that namespace (or its subnamespaces). By default, the "Zend"
                        namespace is registered, pointing to the arent directory of the file
                        defining the <classname>StandardAutoloader</classname>.
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>prefixes</term>

                <listitem>
                    <para>
                        An associative array of vendor prefix/path pairs. The path should be an absolute
                        path or path relative to the calling script, and contain only classes that
                        begin with the provided vendor prefix.
                    </para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>fallback_autoloader</term>

                <listitem>
                    <para>
                        A boolean value indicating whether or not this instance should act as a
                        "fallback" autoloader (i.e., look for classes of any namespace or vendor
                        prefix on the <varname>include_path</varname>). By default,
                        <constant>false</constant>.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </sect2>

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

        <refentry id="zend.loader.standard-autoloader.methods.constructor">
            <refnamediv>
                <refname>__construct</refname>
                <refpurpose>Initialize a new instance of the object</refpurpose>
            </refnamediv>

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

            <refsection>
                <title>Constructor</title>

                <para>
                    Takes an optional <varname>$options</varname> argument. This argument may be an
                    associative array or <interfacename>Traversable</interfacename> object. If not
                    null, the argument is passed to <link linkend="zend.loader.standard-autoloader.methods.set-options"><methodname>setOptions()</methodname></link>.
                </para>
            </refsection>
        </refentry>

        <refentry id="zend.loader.standard-autoloader.methods.set-options">
            <refnamediv>
                <refname>setOptions</refname>
                <refpurpose>Set object state based on provided options.</refpurpose>
            </refnamediv>

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

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

                <para>
                    Takes an argument of either an associative array or
                    <interfacename>Traversable</interfacename> object. Recognized keys are detailed
                    under <xref linkend="zend.loader.standard-autoloader.options"/>, with the
                    following behaviors:
                </para>

                <itemizedlist>
                    <listitem>
                        <para>
                            The <varname>namespaces</varname> value will be passed to <link linkend="zend.loader.standard-autoloader.methods.register-namespaces">registerNamespaces()</link>.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            The <varname>prefixes</varname> value will be passed to <link linkend="zend.loader.standard-autoloader.methods.register-prefixes">registerPrefixes()</link>.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            The <varname>fallback_autoloader</varname> value will be passed to <link linkend="zend.loader.standard-autoloader.methods.set-fallback-autoloader">setFallbackAutoloader()</link>.
                        </para>
                    </listitem>
                </itemizedlist>
            </refsection>
        </refentry>

        <refentry id="zend.loader.standard-autoloader.methods.set-fallback-autoloader">
            <refnamediv>
                <refname>setFallbackAutoloader</refname>
                <refpurpose>Enable/disable fallback autoloader status</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>setFallbackAutoloader</methodname>
                    <methodparam>
                        <funcparams>$flag</funcparams>
                    </methodparam>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsection>
                <title>setFallbackAutoloader()</title>
                
                <para>
                    Takes a boolean flag indicating whether or not to act as a fallback autoloader
                    when registered with the SPL autoloader.
                </para>
            </refsection>
        </refentry>

        <refentry id="zend.loader.standard-autoloader.methods.is-fallback-autoloader">
            <refnamediv>
                <refname>isFallbackAutoloader</refname>
                <refpurpose>Query fallback autoloader status</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>isFallbackAutoloader</methodname>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsection>
                <title>isFallbackAutoloader()</title>

                <para>
                    Indicates whether or not this instance is flagged as a fallback autoloader.
                </para>
            </refsection>
        </refentry>

        <refentry id="zend.loader.standard-autoloader.methods.register-namespace">
            <refnamediv>
                <refname>registerNamespace</refname>
                <refpurpose>Register a namespace with the autoloader</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>registerNamespace</methodname>
                    <methodparam>
                        <funcparams>$namespace, $directory</funcparams>
                    </methodparam>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsection>
                <title>registerNamespace()</title>

                <para>
                    Register a namespace with the autoloader, pointing it to a specific directory on
                    the filesystem for class resolution. For classes matching that initial
                    namespace, the autoloader will then perform lookups within that directory.
                </para>
            </refsection>
        </refentry>

        <refentry id="zend.loader.standard-autoloader.methods.register-namespaces">
            <refnamediv>
                <refname>registerNamespaces</refname>
                <refpurpose>Register multiple namespaces with the autoloader</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>registerNamespaces</methodname>
                    <methodparam>
                        <funcparams>$namespaces</funcparams>
                    </methodparam>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsection>
                <title>registerNamespaces()</title>

                <para>
                    Accepts either an array or <interfacename>Traversable</interfacename> object. It
                    will then iterate through the argument, and pass each item to <link linkend="zend.loader.standard-autoloader.methods.register-namespace">registerNamespace()</link>.
                </para>
            </refsection>
        </refentry>

        <refentry id="zend.loader.standard-autoloader.methods.register-prefix">
            <refnamediv>
                <refname>registerPrefix</refname>
                <refpurpose>Register a vendor prefix with the autoloader.</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>registerPrefix</methodname>
                    <methodparam>
                        <funcparams>$prefix, $directory</funcparams>
                    </methodparam>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsection>
                <title>registerPrefix()</title>

                <para>
                    Register a vendor prefix with the autoloader, pointing it to a specific
                    directory on the filesystem for class resolution. For classes matching that
                    initial vendor prefix, the autoloader will then perform lookups within that
                    directory.
                </para>
            </refsection>
        </refentry>

        <refentry id="zend.loader.standard-autoloader.methods.register-prefixes">
            <refnamediv>
                <refname>registerPrefixes</refname>
                <refpurpose>Register many vendor prefixes with the autoloader</refpurpose>
            </refnamediv>

            <refsynopsisdiv>
                <methodsynopsis>
                    <methodname>registerPrefixes</methodname>
                    <methodparam>
                        <funcparams>$prefixes</funcparams>
                    </methodparam>
                </methodsynopsis>
            </refsynopsisdiv>

            <refsection>
                <title>registerPrefixes()</title>

                <para>
                    Accepts either an array or <interfacename>Traversable</interfacename> object. It
                    will then iterate through the argument, and pass each item to <link linkend="zend.loader.standard-autoloader.methods.register-prefix">registerPrefix()</link>.
                </para>
            </refsection>
        </refentry>

        <refentry id="zend.loader.standard-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.standard-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.standard-autoloader.examples">
        <title>Examples</title>

        <para>
            Please review the <link linkend="zend.loader.standard-autoloader.quick-start">examples
                in the quick start</link> for usage.
        </para>
    </sect2>
</sect1>