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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="learning.autoloading.resources">
   4     <title>Resource Autoloading</title>
   5
   6     <para>
   7         Often, when developing an application, it's either difficult to package classes in the 1:1
   8         classname:filename standard Zend Framework recommends, or it's advantageous for purposes of
   9         packaging not to do so. However, this means you class files will not be found by the
  10         autoloader.
  11     </para>
  12
  13     <para>
  14         If you read through <link linkend="learning.autoloading.design">the design goals</link> for
  15         the autoloader, the last point in that section indicated that the solution should cover this
  16         situation. Zend Framework does so with
  17         <classname>Zend_Loader_Autoloader_Resource</classname>.
  18     </para>
  19
  20     <para>
  21         A resource is just a name that corresponds to a component namespace (which
  22         is appended to the autoloader's namespace) and a path (which is relative to
  23         the autoloader's base path). In action, you'd do something like this:
  24     </para>
  25
  26     <programlisting language="php"><![CDATA[
  27 $loader = new Zend_Application_Module_Autoloader(array(
  28     'namespace' => 'Blog',
  29     'basePath'  => APPLICATION_PATH . '/modules/blog',
  30 ));
  31 ]]></programlisting>
  32
  33     <para>
  34         Once you have the loader in place, you then need to inform it of the various resource types
  35         it's aware of. These resource types are simply pairs of subtree and prefix.
  36     </para>
  37
  38     <para>
  39         As an example, consider the following tree:
  40     </para>
  41
  42     <programlisting language="text"><![CDATA[
  43 path/to/some/resources/
  44 |-- forms/
  45 |   `-- Guestbook.php        // Foo_Form_Guestbook
  46 |-- models/
  47 |   |-- DbTable/
  48 |   |   `-- Guestbook.php    // Foo_Model_DbTable_Guestbook
  49 |   |-- Guestbook.php        // Foo_Model_Guestbook
  50 |   `-- GuestbookMapper.php  // Foo_Model_GuestbookMapper
  51 ]]></programlisting>
  52
  53     <para>
  54         Our first step is creating the resource loader:
  55     </para>
  56
  57     <programlisting language="php"><![CDATA[
  58 $loader = new Zend_Loader_Autoloader_Resource(array(
  59     'basePath'  => 'path/to/some/resources/',
  60     'namespace' => 'Foo',
  61 ));
  62 ]]></programlisting>
  63
  64     <para>
  65         Next, we need to define some resource types.
  66         <methodname>Zend_Loader_Autoloader_Resourse::addResourceType()</methodname> has three
  67         arguments: the "type" of resource (an arbitrary string), the path under the base path in
  68         which the resource type may be found, and the component prefix to use for the resource type.
  69         In the above tree, we have three resource types: form (in the subdirectory "forms", with a
  70         component prefix of "Form"), model (in the subdirectory "models", with a component prefix of
  71         "Model"), and dbtable (in the subdirectory "<filename>models/DbTable</filename>",
  72         with a component prefix of "<classname>Model_DbTable</classname>"). We'd define them as
  73         follows:
  74     </para>
  75
  76     <programlisting language="php"><![CDATA[
  77 $loader->addResourceType('form', 'forms', 'Form')
  78        ->addResourceType('model', 'models', 'Model')
  79        ->addResourceType('dbtable', 'models/DbTable', 'Model_DbTable');
  80 ]]></programlisting>
  81
  82     <para>
  83         Once defined, we can simply use these classes:
  84     </para>
  85
  86     <programlisting language="php"><![CDATA[
  87 $form      = new Foo_Form_Guestbook();
  88 $guestbook = new Foo_Model_Guestbook();
  89 ]]></programlisting>
  90
  91     <note>
  92         <title>Module Resource Autoloading</title>
  93
  94         <para>
  95             Zend Framework's <acronym>MVC</acronym> layer encourages the use of "modules", which
  96             are self-contained applications within your site. Modules typically have a number of
  97             resource types by default, and Zend Framework even
  98             <link linkend="project-structure.filesystem">recommends a standard directory layout
  99                 for modules</link>. Resource autoloaders are therefore
 100             quite useful in this paradigm -- so useful that they are enabled by default when you
 101             create a bootstrap class for your module that extends
 102             <classname>Zend_Application_Module_Bootstrap</classname>. For more information, read
 103             the <link
 104                 linkend="zend.loader.autoloader-resource.module">Zend_Loader_Autoloader_Module
 105                 documentation</link>.
 106         </para>
 107     </note>
 108 </sect1>