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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="learning.autoloading.usage">
   4     <title>Basic Autoloader Usage</title>
   5
   6     <para>
   7         Now that we have an understanding of what autoloading is and the goals and design of Zend
   8         Framework's autoloading solution, let's look at how to use
   9         <classname>Zend_Loader_Autoloader</classname>.
  10     </para>
  11
  12     <para>
  13         In the simplest case, you would simply require the class, and then instantiate it. Since
  14         <classname>Zend_Loader_Autoloader</classname> is a singleton (due to the fact that the
  15         <acronym>SPL</acronym> autoloader is a single resource), we use
  16         <methodname>getInstance()</methodname> to retrieve an instance.
  17     </para>
  18
  19     <programlisting language="php"><![CDATA[
  20 require_once 'Zend/Loader/Autoloader.php';
  21 Zend_Loader_Autoloader::getInstance();
  22 ]]></programlisting>
  23
  24     <para>
  25         By default, this will allow loading any classes with the class namespace prefixes of "Zend_"
  26         or "ZendX_", as long as they are on your <property>include_path</property>.
  27     </para>
  28
  29     <para>
  30         What happens if you have other namespace prefixes you wish to use? The best, and simplest,
  31         way is to call the <methodname>registerNamespace()</methodname> method on the instance. You
  32         can pass a single namespace prefix, or an array of them:
  33     </para>
  34
  35     <programlisting language="php"><![CDATA[
  36 require_once 'Zend/Loader/Autoloader.php';
  37 $loader = Zend_Loader_Autoloader::getInstance();
  38 $loader->registerNamespace('Foo_');
  39 $loader->registerNamespace(array('Foo_', 'Bar_'));
  40 ]]></programlisting>
  41
  42     <para>
  43         Alternately, you can tell <classname>Zend_Loader_Autoloader</classname> to act as a
  44         "fallback" autoloader. This means that it will try to resolve any class regardless of
  45         namespace prefix.
  46     </para>
  47
  48     <programlisting language="php"><![CDATA[
  49 $loader->setFallbackAutoloader(true);
  50 ]]></programlisting>
  51
  52     <warning>
  53         <title>Do not use as a fallback autoloader</title>
  54
  55         <para>
  56             While it's tempting to use <classname>Zend_Loader_Autoloader</classname> as a fallback
  57             autoloader, we do not recommend the practice.
  58         </para>
  59
  60         <para>
  61             Internally, <classname>Zend_Loader_Autoloader</classname> uses
  62             <methodname>Zend_Loader::loadClass()</methodname> to load classes. That method uses
  63             <methodname>include()</methodname> to attempt to load the given class file.
  64             <methodname>include()</methodname> will return a boolean <constant>FALSE</constant>
  65             if not successful -- but also issues a <acronym>PHP</acronym> warning. This latter
  66             fact can lead to some issues:
  67         </para>
  68
  69         <itemizedlist>
  70             <listitem>
  71                 <para>
  72                     If <property>display_errors</property> is enabled, the warning will be included
  73                     in output.
  74                 </para>
  75             </listitem>
  76
  77             <listitem>
  78                 <para>
  79                     Depending on the <property>error_reporting</property> level you have chosen, it
  80                     could also clutter your logs.
  81                 </para>
  82             </listitem>
  83         </itemizedlist>
  84
  85         <para>
  86             You can suppress the error messages (the <classname>Zend_Loader_Autoloader</classname>
  87             documentation details this), but note that the suppression is only relevant when
  88             <property>display_errors</property> is enabled; the error log will always display the
  89             messages. For these reasons, we recommend always configuring the namespace prefixes the
  90             autoloader should be aware of
  91         </para>
  92     </warning>
  93
  94     <note>
  95         <title>Namespace Prefixes vs PHP Namespaces</title>
  96
  97         <para>
  98             At the time this is written, <acronym>PHP</acronym> 5.3 has been released. With that
  99             version, <acronym>PHP</acronym> now has official namespace support.
 100         </para>
 101
 102         <para>
 103             However, Zend Framework predates <acronym>PHP</acronym> 5.3, and thus namespaces.
 104             Within Zend Framework, when we refer to "namespaces", we are referring to a practice
 105             whereby classes are prefixed with a vender "namespace". As an example, all Zend
 106             Framework class names are prefixed with "Zend_" -- that is our vendor "namespace".
 107         </para>
 108
 109         <para>
 110             Zend Framework plans to offer native <acronym>PHP</acronym> namespace support to the
 111             autoloader in future revisions, and its own library will utilize namespaces starting
 112             with version 2.0.0.
 113         </para>
 114     </note>
 115
 116     <para>
 117         If you have a custom autoloader you wish to use with Zend Framework -- perhaps an autoloader
 118         from a third-party library you are also using -- you can manage it with
 119         <classname>Zend_Loader_Autoloader</classname>'s <methodname>pushAutoloader()</methodname>
 120         and <methodname>unshiftAutoloader()</methodname> methods. These methods will append or
 121         prepend, respectively, autoloaders to a chain that is called prior to executing Zend
 122         Framework's internal autoloading mechanism. This approach offers the following benefits:
 123     </para>
 124
 125     <itemizedlist>
 126         <listitem>
 127             <para>
 128                 Each method takes an optional second argument, a class namespace prefix. This can be
 129                 used to indicate that the given autoloader should only be used when looking up
 130                 classes with that given class prefix. If the class being resolved does not have that
 131                 prefix, the autoloader will be skipped -- which can lead to performance
 132                 improvements.
 133             </para>
 134         </listitem>
 135
 136         <listitem>
 137             <para>
 138                 If you need to manipulate <methodname>spl_autoload()</methodname>'s registry, any
 139                 autoloaders that are callbacks pointing to instance methods can pose issues, as
 140                 <methodname>spl_autoload_functions()</methodname> does not return the exact same
 141                 callbacks. <classname>Zend_Loader_Autoloader</classname> has no such limitation.
 142             </para>
 143         </listitem>
 144     </itemizedlist>
 145
 146     <para>
 147         Autoloaders managed this way may be any valid <acronym>PHP</acronym> callback.
 148     </para>
 149
 150     <programlisting language="php"><![CDATA[
 151 // Append function 'my_autoloader' to the stack,
 152 // to manage classes with the prefix 'My_':
 153 $loader->pushAutoloader('my_autoloader', 'My_');
 154
 155 // Prepend static method Foo_Loader::autoload() to the stack,
 156 // to manage classes with the prefix 'Foo_':
 157 $loader->unshiftAutoloader(array('Foo_Loader', 'autoload'), 'Foo_');
 158 ]]></programlisting>
 159 </sect1>