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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="learning.autoloading.design">
   4     <title>Goals and Design</title>
   5
   6     <sect2 id="learning.autoloading.design.naming">
   7         <title>Class Naming Conventions</title>
   8
   9         <para>
  10             To understand autoloading in Zend Framework, first you need to understand the
  11             relationship between class names and class files.
  12         </para>
  13
  14         <para>
  15             Zend Framework has borrowed an idea from <ulink url="http://pear.php.net/">PEAR</ulink>,
  16             whereby class names have a 1:1 relationship with the filesystem. Simply put, the
  17             underscore character ("_") is replaced by a directory separator in order to resolve
  18             the path to the file, and then the suffix "<filename>.php</filename>" is added. For
  19             example, the class "<classname>Foo_Bar_Baz</classname>" would correspond to
  20             "<filename>Foo/Bar/Baz.php</filename>" on the filesystem. The assumption is also
  21             that the classes may be resolved via <acronym>PHP</acronym>'s
  22             <property>include_path</property> setting, which allows both
  23             <methodname>include()</methodname> and <methodname>require()</methodname> to find
  24             the filename via a relative path lookup on the <property>include_path</property>.
  25         </para>
  26
  27         <para>
  28             Additionally, per <acronym>PEAR</acronym> as well as the <ulink
  29                 url="http://php.net/userlandnaming.tips">PHP project</ulink>, we use and recommend
  30             using a vendor or project prefix for your code. What this means is that all classes you
  31             write will share a common class prefix; for example, all code in Zend Framework has the
  32             prefix "Zend_". This naming convention helps prevent naming collisions. Within Zend
  33             Framework, we often refer to this as the "namespace" prefix; be careful not to confuse
  34             it with <acronym>PHP</acronym>'s native namespace implementation.
  35         </para>
  36
  37         <para>
  38             Zend Framework follows these simple rules internally, and our coding standards encourage
  39             that you do so as well for all library code.
  40         </para>
  41     </sect2>
  42
  43     <sect2 id="learning.autoloading.design.autoloader">
  44         <title>Autoloader Conventions and Design</title>
  45
  46         <para>
  47             Zend Framework's autoloading support, provided primarily via
  48             <classname>Zend_Loader_Autoloader</classname>, has the following goals and design
  49             elements:
  50         </para>
  51
  52         <itemizedlist>
  53             <listitem>
  54                 <para>
  55                     <emphasis>Provide namespace matching</emphasis>. If the class
  56                     namespace prefix is not in a list of registered namespaces, return
  57                     <constant>FALSE</constant> immediately. This allows for more optimistic
  58                     matching, as well as fallback to other autoloaders.
  59                 </para>
  60             </listitem>
  61
  62             <listitem>
  63                 <para>
  64                     <emphasis>Allow the autoloader to act as a fallback autoloader</emphasis>.
  65                     In the case where a team may be widely distributed, or using an undetermined
  66                     set of namespace prefixes, the autoloader should still be configurable such
  67                     that it will attempt to match any namespace prefix. It will be noted,
  68                     however, that this practice is not recommended, as it can lead to
  69                     unnecessary lookups.
  70                 </para>
  71             </listitem>
  72
  73             <listitem>
  74                 <para>
  75                     <emphasis>Allow toggling error suppression</emphasis>. We feel -- and the
  76                     greater <acronym>PHP</acronym> community does as well -- that error suppression
  77                     is a bad idea. It's expensive, and it masks very real application problems.
  78                     So, by default, it should be off. However, if a developer
  79                     <emphasis>insists</emphasis> that it be on, we allow toggling it on.
  80                 </para>
  81             </listitem>
  82
  83             <listitem>
  84                 <para>
  85                     <emphasis>Allow specifying custom callbacks for autoloading</emphasis>.
  86                     Some developers don't want to use
  87                     <methodname>Zend_Loader::loadClass()</methodname> for autoloading, but still
  88                     want to make use of Zend Framework's mechanisms.
  89                     <classname>Zend_Loader_Autoloader</classname> allows specyfing an alternate
  90                     callback for autoloading.
  91                 </para>
  92             </listitem>
  93
  94             <listitem>
  95                 <para>
  96                     <emphasis>Allow manipulation of the <acronym>SPL</acronym> autoload
  97                     callback chain</emphasis>. The purpose of this is to allow specifying
  98                     additional autoloaders -- for instance, resource loaders for classes
  99                     that don't have a 1:1 mapping to the filesystem -- to be registered before
 100                     or after the primary Zend Framework autoloader.
 101                 </para>
 102             </listitem>
 103         </itemizedlist>
 104     </sect2>
 105 </sect1>