documentation/manual/en/module_specs/Zend_Loader.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.loader.load">
   4     <title>Loading Files and Classes Dynamically</title>
   5
   6     <para>
   7         The <classname>Zend_Loader</classname> class includes methods to help you load files
   8         dynamically.
   9     </para>
  10
  11     <tip>
  12         <title>Zend_Loader vs. require_once()</title>
  13
  14         <para>
  15             The <classname>Zend_Loader</classname> methods are best used if the filename you need to
  16             load is variable. For example, if it is based on a parameter from
  17             user input or method argument. If you are loading a file or a
  18             class whose name is constant, there is no benefit to using
  19             <classname>Zend_Loader</classname> over using traditional <acronym>PHP</acronym>
  20             functions such as <ulink
  21                 url="http://php.net/require_once"><methodname>require_once()</methodname></ulink>.
  22         </para>
  23     </tip>
  24
  25     <sect2 id="zend.loader.load.file">
  26         <title>Loading Files</title>
  27
  28         <para>
  29             The static method <methodname>Zend_Loader::loadFile()</methodname> loads a
  30             <acronym>PHP</acronym> file. The file loaded may contain any <acronym>PHP</acronym>
  31             code. The method is a wrapper for the <acronym>PHP</acronym> function
  32             <ulink url="http://php.net/include"><methodname>include()</methodname></ulink>.
  33             This method returns boolean <constant>FALSE</constant> on failure, for example
  34             if the specified file does not exist.
  35         </para>
  36
  37         <example id="zend.loader.load.file.example">
  38             <title>Example of the loadFile() Method</title>
  39
  40             <programlisting language="php"><![CDATA[
  41 Zend_Loader::loadFile($filename, $dirs=null, $once=false);
  42 ]]></programlisting>
  43     </example>
  44
  45         <para>
  46             The <varname>$filename</varname> argument specifies the filename to load,
  47             which must not contain any path information.
  48             A security check is performed on <varname>$filename</varname>.
  49             The <varname>$filename</varname> may only contain alphanumeric characters,
  50             dashes ("-"), underscores ("_"), or periods (".").
  51             No such restriction is placed on the <varname>$dirs</varname> argument.
  52         </para>
  53
  54         <para>
  55             The <varname>$dirs</varname> argument specifies which directories to search for the
  56             file in. If the value is <constant>NULL</constant>, only the <code>include_path</code>
  57             is searched; if the value is a string or an array, the directory or directories
  58             specified will be searched, followed by the <code>include_path</code>.
  59         </para>
  60
  61         <para>
  62             The <varname>$once</varname> argument is a boolean. If <constant>TRUE</constant>,
  63             <methodname>Zend_Loader::loadFile()</methodname> uses the <acronym>PHP</acronym>
  64             function <ulink
  65                 url="http://php.net/include"><methodname>include_once()</methodname></ulink>
  66             for loading the file, otherwise the <acronym>PHP</acronym> function
  67             <ulink url="http://php.net/include_once"><methodname>include()</methodname></ulink>
  68             is used.
  69         </para>
  70     </sect2>
  71
  72     <sect2 id="zend.loader.load.class">
  73         <title>Loading Classes</title>
  74
  75         <para>
  76             The static method <methodname>Zend_Loader::loadClass($class, $dirs)</methodname>
  77             loads a <acronym>PHP</acronym> file and then checks for the existence of the class.
  78         </para>
  79
  80         <example id="zend.loader.load.class.example">
  81             <title>Example of the loadClass() Method</title>
  82
  83             <programlisting language="php"><![CDATA[
  84 Zend_Loader::loadClass('Container_Tree',
  85     array(
  86         '/home/production/mylib',
  87         '/home/production/myapp'
  88     )
  89 );
  90 ]]></programlisting>
  91         </example>
  92
  93         <para>
  94             The string specifying the class is converted to a relative path
  95             by substituting underscores with directory separators for your OS, and appending
  96             '.php'. In the example above, 'Container_Tree' becomes 'Container\\Tree.php' on Windows.
  97         </para>
  98
  99         <para>
 100             If <varname>$dirs</varname> is a string or an array,
 101             <methodname>Zend_Loader::loadClass()</methodname> searches the directories in
 102             the order supplied. The first matching file is loaded. If the file
 103             does not exist in the specified <varname>$dirs</varname>, then the
 104             <code>include_path</code> for the <acronym>PHP</acronym> environment is searched.
 105         </para>
 106
 107         <para>
 108             If the file is not found or the class does not exist after the load,
 109             <methodname>Zend_Loader::loadClass()</methodname> throws a
 110             <classname>Zend_Exception</classname>.
 111         </para>
 112
 113         <para>
 114             <methodname>Zend_Loader::loadFile()</methodname> is used for loading, so the
 115             class name may only contain alphanumeric characters and the hyphen
 116             ('-'), underscore ('_'), and period ('.').
 117         </para>
 118
 119         <note>
 120             <title>Loading Classes from PHP Namespaces</title>
 121
 122             <para>
 123                 Starting in version 1.10.0, Zend Framework now allows loading classes from
 124                 <acronym>PHP</acronym> namespaces. This support follows the same guidelines and
 125                 implementation as that found in the <ulink
 126                     url="http://groups.google.com/group/php-standards/web/psr-0-final-proposal">PHP
 127                 Framework Interop Group PSR-0</ulink> reference implementation.
 128             </para>
 129
 130             <para>
 131                 Under this guideline, the following rules apply:
 132             </para>
 133
 134             <itemizedlist>
 135                 <listitem>
 136                     <para>
 137                         Each namespace separator is converted to a
 138                         <constant>DIRECTORY_SEPARATOR</constant> when loading from the file system.
 139                     </para>
 140                 </listitem>
 141
 142                 <listitem>
 143                     <para>
 144                         Each "_" character in the <emphasis>CLASS NAME</emphasis> is converted to a
 145                         <constant>DIRECTORY_SEPARATOR</constant>. The "_" character has no special
 146                         meaning in the namespace.
 147                     </para>
 148                 </listitem>
 149
 150                 <listitem>
 151                     <para>
 152                         The fully-qualified namespace and class is suffixed with ".php" when loading
 153                         from the file system.
 154                     </para>
 155                 </listitem>
 156             </itemizedlist>
 157
 158             <para>
 159                 As examples:
 160             </para>
 161
 162             <itemizedlist>
 163                 <listitem>
 164                     <para>
 165                         <classname>\Doctrine\Common\IsolatedClassLoader</classname> =&gt;
 166                         <filename>/path/to/project/lib/vendor/Doctrine/Common/IsolatedClassLoader.php</filename>
 167                     </para>
 168                 </listitem>
 169
 170                 <listitem>
 171                     <para>
 172                         <classname>\namespace\package\Class_Name</classname> =&gt;
 173                         <filename>/path/to/project/lib/vendor/namespace/package/Class/Name.php</filename>
 174                     </para>
 175                 </listitem>
 176
 177                 <listitem>
 178                     <para>
 179                         <classname>\namespace\package_name\Class_Name</classname> =&gt;
 180                         <filename>/path/to/project/lib/vendor/namespace/package_name/Class/Name.php</filename>
 181                     </para>
 182                 </listitem>
 183             </itemizedlist>
 184         </note>
 185     </sect2>
 186
 187     <sect2 id="zend.loader.load.isreadable">
 188         <title>Testing if a File is Readable</title>
 189
 190         <para>
 191             The static method <methodname>Zend_Loader::isReadable($pathname)</methodname>
 192             returns <constant>TRUE</constant> if a file at the specified pathname exists
 193             and is readable, <constant>FALSE</constant> otherwise.
 194         </para>
 195
 196         <example id="zend.loader.load.isreadable.example">
 197             <title>Example of isReadable() method</title>
 198
 199             <programlisting language="php"><![CDATA[
 200 if (Zend_Loader::isReadable($filename)) {
 201     // do something with $filename
 202 }
 203 ]]></programlisting>
 204         </example>
 205
 206         <para>
 207             The <varname>$filename</varname> argument specifies the filename to
 208             check. This may contain path information.
 209             This method is a wrapper for the <acronym>PHP</acronym> function
 210             <ulink url="http://php.net/is_readable"><methodname>is_readable()</methodname></ulink>.
 211             The <acronym>PHP</acronym> function does not search the <code>include_path</code>,
 212             while <methodname>Zend_Loader::isReadable()</methodname> does.
 213         </para>
 214     </sect2>
 215
 216     <sect2 id="zend.loader.load.autoload">
 217         <title>Using the Autoloader</title>
 218
 219         <para>
 220             The <classname>Zend_Loader</classname> class contains a method you can register with the
 221             <acronym>PHP</acronym> SPL autoloader. <methodname>Zend_Loader::autoload()</methodname>
 222             is the callback method. As a convenience, <classname>Zend_Loader</classname> provides
 223             the <methodname>registerAutoload()</methodname> function to register its
 224             <methodname>autoload()</methodname> method. If the <code>spl_autoload</code>
 225             extension is not present in your <acronym>PHP</acronym> environment, then the
 226             <methodname>registerAutoload()</methodname> method throws a
 227             <classname>Zend_Exception</classname>.
 228         </para>
 229
 230         <example id="zend.loader.load.autoload.example">
 231             <title>Example of registering the autoloader callback method</title>
 232
 233             <programlisting language="php"><![CDATA[
 234 Zend_Loader::registerAutoload();
 235 ]]></programlisting>
 236         </example>
 237
 238         <para>
 239             After registering the Zend Framework autoload callback, you can
 240             reference classes from Zend Framework without having to load
 241             them explicitly. The <methodname>autoload()</methodname> method uses
 242             <methodname>Zend_Loader::loadClass()</methodname> automatically when you
 243             reference a class.
 244         </para>
 245
 246         <para>
 247             If you have extended the <classname>Zend_Loader</classname> class, you can give an
 248             optional argument to <methodname>registerAutoload()</methodname>, to specify
 249             the class from which to register an <methodname>autoload()</methodname> method.
 250         </para>
 251
 252         <example id="zend.loader.load.autoload.example-extended">
 253             <title>Example of registering the autoload callback method from an
 254                 extended class</title>
 255
 256             <para>
 257                 Because of the semantics of static function references in <acronym>PHP</acronym>,
 258                 you must implement code for both <methodname>loadClass()</methodname>
 259                 and <methodname>autoload()</methodname>, and the <methodname>autoload()</methodname>
 260                 must call <methodname>self::loadClass()</methodname>. If your
 261                 <methodname>autoload()</methodname> method delegates to its parent to
 262                 call <methodname>self::loadClass()</methodname>, then it calls the
 263                 method of that name in the parent class, not the subclass.
 264             </para>
 265
 266             <programlisting language="php"><![CDATA[
 267 class My_Loader extends Zend_Loader
 268 {
 269     public static function loadClass($class, $dirs = null)
 270     {
 271         parent::loadClass($class, $dirs);
 272     }
 273
 274     public static function autoload($class)
 275     {
 276         try {
 277             self::loadClass($class);
 278             return $class;
 279         } catch (Exception $e) {
 280             return false;
 281         }
 282     }
 283 }
 284
 285 Zend_Loader::registerAutoload('My_Loader');
 286 ]]></programlisting>
 287         </example>
 288
 289         <para>
 290             You can remove an autoload callback. The
 291             <methodname>registerAutoload()</methodname> has an optional second argument,
 292             which is <constant>TRUE</constant> by default. If this argument is
 293             <constant>FALSE</constant>, the autoload callback is unregistered from the
 294             SPL autoload stack.
 295         </para>
 296     </sect2>
 297 </sect1>
 298 <!--
 299 vim:se ts=4 sw=4 et:
 300 -->