documentation/manual/en/module_specs/Zend_Loader-Autoloader-Resource.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.loader.autoloader-resource">
   4     <title>Resource Autoloaders</title>
   5
   6     <para>
   7         Resource autoloaders are intended to manage namespaced library code that
   8         follow Zend Framework coding standard guidelines, but which do not have
   9         a 1:1 mapping between the class name and the directory structure. Their
  10         primary purpose is to facilitate autoloading application resource code,
  11         such as application-specific models, forms, and <acronym>ACL</acronym>s.
  12     </para>
  13
  14     <para>
  15         Resource autoloaders register with the <link
  16             linkend="zend.loader.autoloader">autoloader</link> on instantiation,
  17         with the namespace to which they are associated. This allows you to
  18         easily namespace code in specific directories, and still reap the
  19         benefits of autoloading.
  20     </para>
  21
  22     <sect2 id="zend.loader.autoloader-resource.usage">
  23         <title>Resource autoloader usage</title>
  24
  25         <para>
  26             Let's consider the following directory structure:
  27         </para>
  28
  29         <programlisting language="text"><![CDATA[
  30 path/to/some/directory/
  31     acls/
  32         Site.php
  33     forms/
  34         Login.php
  35     models/
  36         User.php
  37 ]]></programlisting>
  38
  39         <para>
  40             Within this directory, all code is prefixed with the namespace
  41             "My_". Within the "acls" subdirectory, the component prefix "Acl_"
  42             is added, giving a final class name of "My_Acl_Site". Similarly, the
  43             "forms" subdirectory maps to "Form_", giving "My_Form_Login". The
  44             "models" subdirectory has no component namespace, giving "My_User".
  45         </para>
  46
  47         <para>
  48             You can use a resource autoloader to autoload these classes. To
  49             instantiate the resource autoloader, you are required to pass at the
  50             minimum the base path and namespace for the resources it will be
  51             responsible for:
  52         </para>
  53
  54         <programlisting language="php"><![CDATA[
  55 $resourceLoader = new Zend_Loader_Autoloader_Resource(array(
  56     'basePath'  => 'path/to/some/directory',
  57     'namespace' => 'My',
  58 ));
  59 ]]></programlisting>
  60
  61         <note>
  62             <title>Base namespace</title>
  63
  64             <para>
  65                 In <classname>Zend_Loader_Autoloader</classname>, you are expected to
  66                 provide the trailing underscore ("_") in your namespace if your
  67                 autoloader will use it to match the namespace.
  68                 <classname>Zend_Loader_Autoloader_Resource</classname> makes the
  69                 assumption that all code you are autoloading will use an
  70                 underscore separator between namespaces, components, and
  71                 classes. As a result, you do not need to use the trailing
  72                 underscore when registering a resource autoloader.
  73             </para>
  74         </note>
  75
  76         <para>
  77             Now that we have setup the base resource autoloader, we can add some
  78             components to it to autoload. This is done using the
  79             <methodname>addResourceType()</methodname> method, which accepts three
  80             arguments: a resource "type", used internally as a reference name;
  81             the subdirectory path underneath the base path in which these
  82             resources live; and the component namespace to append to the base
  83             namespace. As an example, let's add each of our resource types.
  84         </para>
  85
  86         <programlisting language="php"><![CDATA[
  87 $resourceLoader->addResourceType('acl', 'acls/', 'Acl')
  88                ->addResourceType('form', 'forms/', 'Form')
  89                ->addResourceType('model', 'models/');
  90 ]]></programlisting>
  91
  92         <para>
  93             Alternately, you could pass these as an array to
  94             <methodname>addResourceTypes()</methodname>; the following is equivalent to the
  95             above:
  96         </para>
  97
  98         <programlisting language="php"><![CDATA[
  99 $resourceLoader->addResourceTypes(array(
 100     'acl' => array(
 101         'path'      => 'acls/',
 102         'namespace' => 'Acl',
 103     ),
 104     'form' => array(
 105         'path'      => 'forms/',
 106         'namespace' => 'Form',
 107     ),
 108     'model' => array(
 109         'path'      => 'models/',
 110     ),
 111 ));
 112 ]]></programlisting>
 113
 114         <para>
 115             Finally, you can specify all of this when instantiating the object,
 116             by simply specifying a "resourceTypes" key in the options passed and
 117             a structure like that above:
 118         </para>
 119
 120         <programlisting language="php"><![CDATA[
 121 $resourceLoader = new Zend_Loader_Autoloader_Resource(array(
 122     'basePath'      => 'path/to/some/directory',
 123     'namespace'     => 'My',
 124     'resourceTypes' => array(
 125         'acl' => array(
 126             'path'      => 'acls/',
 127             'namespace' => 'Acl',
 128         ),
 129         'form' => array(
 130             'path'      => 'forms/',
 131             'namespace' => 'Form',
 132         ),
 133         'model' => array(
 134             'path'      => 'models/',
 135         ),
 136     ),
 137 ));
 138 ]]></programlisting>
 139     </sect2>
 140
 141     <sect2 id="zend.loader.autoloader-resource.module">
 142         <title>The Module Resource Autoloader</title>
 143
 144         <para>
 145             Zend Framework ships with a concrete implementation of
 146             <classname>Zend_Loader_Autoloader_Resource</classname> that contains resource
 147             type mappings that cover the default recommended directory structure
 148             for Zend Framework <acronym>MVC</acronym> applications. This loader,
 149             <classname>Zend_Application_Module_Autoloader</classname>, comes with the
 150             following mappings:
 151         </para>
 152
 153         <programlisting language="text"><![CDATA[
 154 forms/       => Form
 155 models/      => Model
 156     DbTable/ => Model_DbTable
 157     mappers/ => Model_Mapper
 158 plugins/     => Plugin
 159 services/    => Service
 160 views/
 161     helpers  => View_Helper
 162     filters  => View_Filter
 163 ]]></programlisting>
 164
 165         <para>
 166             As an example, if you have a module with the prefix of "Blog_", and
 167             attempted to instantiate the class "Blog_Form_Entry", it would look
 168             in the resource directory's "forms/" subdirectory for a file named
 169             "Entry.php".
 170         </para>
 171
 172         <para>
 173             When using module bootstraps with <classname>Zend_Application</classname>, an
 174             instance of <classname>Zend_Application_Module_Autoloader</classname> will be
 175             created by default for each discrete module, allowing you to
 176             autoload module resources.
 177         </para>
 178     </sect2>
 179
 180     <sect2 id="zend.loader.autoloader-resource.factory">
 181         <title>Using Resource Autoloaders as Object Factories</title>
 182         <para></para>
 183         <!-- @todo -->
 184     </sect2>
 185
 186     <sect2 id="zend.loader.autoloader-resource.reference">
 187         <title>Resource Autoloader Reference</title>
 188         <para></para>
 189         <!-- @todo -->
 190     </sect2>
 191
 192     <!-- @todo
 193             Write section on using load() functionality
 194                 Potentially add functionality to load() to allow passing arguments
 195                 Show how to use overloading to retrieve class instances
 196             Write reference section
 197     -->
 198 </sect1>