repo_zf1/documentation/manual/en/tutorials/autoloading-resources.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="learning.autoloading.resources">
    <title>Resource Autoloading</title>

    <para>
        Often, when developing an application, it's either difficult to package classes in the 1:1
        classname:filename standard Zend Framework recommends, or it's advantageous for purposes of
        packaging not to do so. However, this means you class files will not be found by the
        autoloader.
    </para>

    <para>
        If you read through <link linkend="learning.autoloading.design">the design goals</link> for
        the autoloader, the last point in that section indicated that the solution should cover this
        situation. Zend Framework does so with
        <classname>Zend_Loader_Autoloader_Resource</classname>.
    </para>

    <para>
        A resource is just a name that corresponds to a component namespace (which
        is appended to the autoloader's namespace) and a path (which is relative to
        the autoloader's base path). In action, you'd do something like this:
    </para>

    <programlisting language="php"><![CDATA[
$loader = new Zend_Application_Module_Autoloader(array(
    'namespace' => 'Blog',
    'basePath'  => APPLICATION_PATH . '/modules/blog',
));
]]></programlisting>

    <para>
        Once you have the loader in place, you then need to inform it of the various resource types
        it's aware of. These resource types are simply pairs of subtree and prefix.
    </para>

    <para>
        As an example, consider the following tree:
    </para>

    <programlisting language="text"><![CDATA[
path/to/some/resources/
|-- forms/
|   `-- Guestbook.php        // Foo_Form_Guestbook
|-- models/
|   |-- DbTable/
|   |   `-- Guestbook.php    // Foo_Model_DbTable_Guestbook
|   |-- Guestbook.php        // Foo_Model_Guestbook
|   `-- GuestbookMapper.php  // Foo_Model_GuestbookMapper
]]></programlisting>

    <para>
        Our first step is creating the resource loader:
    </para>

    <programlisting language="php"><![CDATA[
$loader = new Zend_Loader_Autoloader_Resource(array(
    'basePath'  => 'path/to/some/resources/',
    'namespace' => 'Foo',
));
]]></programlisting>

    <para>
        Next, we need to define some resource types.
        <methodname>Zend_Loader_Autoloader_Resourse::addResourceType()</methodname> has three
        arguments: the "type" of resource (an arbitrary string), the path under the base path in
        which the resource type may be found, and the component prefix to use for the resource type.
        In the above tree, we have three resource types: form (in the subdirectory "forms", with a
        component prefix of "Form"), model (in the subdirectory "models", with a component prefix of
        "Model"), and dbtable (in the subdirectory "<filename>models/DbTable</filename>",
        with a component prefix of "<classname>Model_DbTable</classname>"). We'd define them as
        follows:
    </para>

    <programlisting language="php"><![CDATA[
$loader->addResourceType('form', 'forms', 'Form')
       ->addResourceType('model', 'models', 'Model')
       ->addResourceType('dbtable', 'models/DbTable', 'Model_DbTable');
]]></programlisting>

    <para>
        Once defined, we can simply use these classes:
    </para>

    <programlisting language="php"><![CDATA[
$form      = new Foo_Form_Guestbook();
$guestbook = new Foo_Model_Guestbook();
]]></programlisting>

    <note>
        <title>Module Resource Autoloading</title>

        <para>
            Zend Framework's <acronym>MVC</acronym> layer encourages the use of "modules", which
            are self-contained applications within your site. Modules typically have a number of
            resource types by default, and Zend Framework even
            <link linkend="project-structure.filesystem">recommends a standard directory layout
                for modules</link>. Resource autoloaders are therefore
            quite useful in this paradigm -- so useful that they are enabled by default when you
            create a bootstrap class for your module that extends
            <classname>Zend_Application_Module_Bootstrap</classname>. For more information, read
            the <link
                linkend="zend.loader.autoloader-resource.module">Zend_Loader_Autoloader_Module
                documentation</link>.
        </para>
    </note>
</sect1>