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

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

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

        <para>
            While any valid PHP callback may be registered with
            <function>spl_autoload_register()</function>, Zend Framework autoloaders often provide
            more flexibility by being stateful and allowing configuration. To provide a common
            interface, Zend Framework provides the <interfacename>SplAutoloader</interfacename>
            interface.
        </para>

        <para>
            Objects implementing this interface provide a standard mechanism for configuration, a
            method that may be invoked to attempt to load a class, and a method for registering with
            the SPL autoloading mechanism.
        </para>
    </sect2>

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

        <para>
            To create your own autoloading mechanism, simply create a class implementing the
            <interfacename>SplAutoloader</interfacename> interface (you may review the methods
            defined in the <link linkend="zend.loader.spl-autoloader.methods">Methods
            section</link>). As a simple example, consider the following autoloader, which will look
            for a class file named after the class within a list of registered directories.
        </para>

        <programlisting language="php"><![CDATA[
require_once 'Zend/Loader/SplAutoloader.php';

class Custom_ModifiedIncludePathAutoloader implements Zend_Loader_SplAutoloader
{
    protected $paths = array();

    public function __construct($options = null)
    {
        if (null !== $options) {
            $this->setOptions($options);
        }
    }

    public function setOptions($options)
    {
        if (!is_array($options) && !($options instanceof Traversable)) {
            throw new InvalidArgumentException();
        }

        foreach ($options as $path) {
            if (!in_array($path, $this->paths)) {
                $this->paths[] = $path;
            }
        }
        return $this;
    }

    public function autoload($classname)
    {
        $filename = $classname . '.php';
        foreach ($this->paths as $path) {
            $test = $path . DIRECTORY_SEPARATOR . $filename;
            if (file_exists($test)) {
                return include($test);
            }
        }
        return false;
    }

    public function register()
    {
        spl_autoload_register(array($this, 'autoload'));
    }
}
]]></programlisting>
    </sect2>

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

        <para>
            This component defines no configuration options, as it is an interface.
        </para>
    </sect2>

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

        <refentry id="zend.loader.spl-autoloader.methods.constructor">
            <refnamediv>
                <refname>__construct</refname>
                <refpurpose>Initialize and configure an autoloader</refpurpose>
            </refnamediv>

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

            <refsection>
                <title>Constructor</title>

                <para>
                    Autoloader constructors should optionally receive configuration options.
                    Typically, if received, these will be passed to the
                    <methodname>setOptions()</methodname> method to process.
                </para>
            </refsection>
        </refentry>

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

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

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

                <para>
                    Used to configure the autoloader. Typically, it should expect either an array or
                    a <interfacename>Traversable</interfacename> object, though validation of the
                    options is left to implementation. Additionally, it is recommended that the
                    method return the autoloader instance in order to implement a fluent interface.
                </para>
            </refsection>
        </refentry>

        <refentry id="zend.loader.spl-autoloader.methods.autoload">
            <refnamediv>
                <refname>autoload</refname>
                <refpurpose>Attempt to resolve a class name to the file defining it</refpurpose>
            </refnamediv>

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

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

                <para>
                    This method should be used to resolve a class name to the file defining it. When
                    a positive match is found, return the class name; otherwise, return a boolean
                    false.
                </para>
            </refsection>
        </refentry>

        <refentry id="zend.loader.spl-autoloader.methods.register">
            <refnamediv>
                <refname>register</refname>
                <refpurpose>Register the autoloader with the SPL autoloader</refpurpose>
            </refnamediv>

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

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

                <para>
                    Should be used to register the autoloader instance with
                    <function>spl_autoload_register()</function>. Invariably, the method
                    should look like the following:
                </para>

                <programlisting language="php"><![CDATA[
public function register()
{
    spl_autoload_register(array($this, 'autoload'));
}
]]></programlisting>
            </refsection>
        </refentry>
    </sect2>

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

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