documentation/manual/ja/module_specs/Zend_Loader.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <!-- EN-Revision: 21818 -->
   4 <sect1 id="zend.loader.load">
   5
   6     <title>ファイルやクラスの動的な読み込み</title>
   7
   8     <para>
   9         <classname>Zend_Loader</classname> クラスは、ファイルを動的に読み込むためのメソッドを提供します。
  10     </para>
  11
  12     <tip>
  13         <title>Zend_Loader 対 require_once()</title>
  14         <para>
  15             <classname>Zend_Loader</classname> のメソッドは、読み込みたいファイルの名前が変化する場合に便利です。
  16             たとえば、ユーザの入力やメソッドの引数などのパラメータに基づいたファイル名を使用する場合などです。
  17             もし読み込むファイルやクラスの名前が決まっている場合は、
  18             <ulink url="http://php.net/require_once"><methodname>require_once()</methodname></ulink>
  19             のような <acronym>PHP</acronym> の関数ではなくあえて <classname>Zend_Loader</classname> を使用するメリットはありません。
  20         </para>
  21     </tip>
  22
  23     <sect2 id="zend.loader.load.file">
  24
  25         <title>ファイルの読み込み</title>
  26
  27         <para>
  28             静的メソッド <methodname>Zend_Loader::loadFile()</methodname>
  29             は、<acronym>PHP</acronym> ファイルを読み込みます。
  30             読み込まれるファイルには任意の <acronym>PHP</acronym> コードを含めることができます。
  31             このメソッドは <acronym>PHP</acronym> 関数
  32             <ulink url="http://php.net/include"><methodname>include()</methodname></ulink>
  33             のラッパーで、失敗した場合 (たとえば指定したファイルが存在しないなど)
  34             には <constant>FALSE</constant> を返します。
  35         </para>
  36
  37         <example id="zend.loader.load.file.example">
  38             <title>loadFile() メソッドの例</title>
  39             <programlisting language="php"><![CDATA[
  40 Zend_Loader::loadFile($filename, $dirs=null, $once=false);
  41 ]]></programlisting>
  42     </example>
  43
  44         <para>
  45             引数 <code>$filename</code> には読み込むファイル名を指定します。
  46             ここにはパス情報を含めてはいけません。<code>$filename</code>
  47             に対してはセキュリティチェックが行われます。
  48             <code>$filename</code> に含めることができるのは英数字、ダッシュ ("-")、
  49             アンダースコア ("_") あるいはピリオド (".") だけです。
  50             引数 <code>$dirs</code> にはそのような制限はありません。
  51         </para>
  52
  53         <para>
  54             引数 <code>$dirs</code> にはファイルを探すディレクトリを指定します。
  55             <constant>NULL</constant> の場合は <code>include_path</code> の中のみを対象とします。
  56             文字列あるいは配列を指定すると、指定されたディレクトリをまず探した後で、
  57             それから <code>include_path</code> を探します。
  58         </para>
  59
  60         <para>
  61             引数 <code>$once</code> は論理値です。<constant>TRUE</constant> を指定すると、
  62             <methodname>Zend_Loader::loadFile()</methodname> は <acronym>PHP</acronym> の関数
  63             <ulink url="http://php.net/include"><methodname>include_once()</methodname></ulink>
  64             でファイルを読み込みます。それ以外の場合は
  65             <ulink url="http://php.net/include_once"><methodname>include()</methodname></ulink>
  66             を使用します。
  67         </para>
  68
  69     </sect2>
  70
  71     <sect2 id="zend.loader.load.class">
  72
  73         <title>クラスの読み込み</title>
  74
  75         <para>
  76             静的メソッド <methodname>Zend_Loader::loadClass($class, $dirs)</methodname>
  77             は、<acronym>PHP</acronym> ファイルを読み込んでクラスが存在するかどうかを確かめます。
  78         </para>
  79
  80         <example id="zend.loader.load.class.example">
  81             <title>loadClass() メソッドの例</title>
  82             <programlisting language="php"><![CDATA[
  83 Zend_Loader::loadClass('Container_Tree',
  84     array(
  85         '/home/production/mylib',
  86         '/home/production/myapp'
  87     )
  88 );
  89 ]]></programlisting>
  90         </example>
  91
  92         <para>
  93             クラスを指定する文字列は、アンダースコアを OS のパス区切り文字に変換して最後に
  94             '.php' を追加したものとなります。上の例では、Windows 上で
  95             'Container_Tree' は 'Container\\Tree.php' となります。
  96         </para>
  97
  98         <para>
  99             <code>$dirs</code> に文字列あるいは配列を指定すると、
 100             <methodname>Zend_Loader::loadClass()</methodname> は指定した順にそのディレクトリを探します。
 101             そして最初に見つかったファイルを読み込みます。
 102             ディレクトリ <code>$dirs</code> にファイルがみつからない場合は、
 103             <acronym>PHP</acronym> の <code>include_path</code> で指定された場所を探します。
 104         </para>
 105
 106         <para>
 107             ファイルが見つからない場合、あるいは読み込んだファイルにクラスが存在しない場合は
 108             <methodname>Zend_Loader::loadClass()</methodname> は <classname>Zend_Exception</classname>
 109             をスローします。
 110         </para>
 111
 112         <para>
 113             ファイルの読み込みには <methodname>Zend_Loader::loadFile()</methodname> を使用するので、
 114             クラス名として指定できるのは
 115             英数字とハイフン ('-')、アンダースコア ('_') そしてピリオド ('.') だけです。
 116         </para>
 117
 118         <note>
 119             <title>Loading Classes from PHP Namespaces</title>
 120
 121             <para>
 122                 Starting in version 1.10.0, Zend Framework now allows loading classes from <acronym>PHP</acronym>
 123                 namespaces. This support follows the same guidelines and implementation as that
 124                 found in the <ulink
 125                     url="http://groups.google.com/group/php-standards/web/psr-0-final-proposal">PHP
 126                 Framework Interop Group PSR-0</ulink> reference implementation.
 127             </para>
 128
 129             <para>
 130                 Under this guideline, the following rules apply:
 131             </para>
 132
 133             <itemizedlist>
 134                 <listitem>
 135                     <para>
 136                         Each namespace separator is converted to a
 137                         <constant>DIRECTORY_SEPARATOR</constant> when loading from the file system.
 138                     </para>
 139                 </listitem>
 140
 141                 <listitem>
 142                     <para>
 143                         Each "_" character in the <emphasis>CLASS NAME</emphasis> is converted to a
 144                         <constant>DIRECTORY_SEPARATOR</constant>.  The "_" character has no special
 145                         meaning in the namespace.
 146                     </para>
 147                 </listitem>
 148
 149                 <listitem>
 150                     <para>
 151                         The fully-qualified namespace and class is suffixed with ".php" when loading
 152                         from the file system.
 153                     </para>
 154                 </listitem>
 155             </itemizedlist>
 156
 157             <para>
 158                 As examples:
 159             </para>
 160
 161             <itemizedlist>
 162                 <listitem>
 163                     <para>
 164                         <classname>\Doctrine\Common\IsolatedClassLoader</classname> =&gt;
 165                         <filename>/path/to/project/lib/vendor/Doctrine/Common/IsolatedClassLoader.php</filename>
 166                     </para>
 167                 </listitem>
 168
 169                 <listitem>
 170                     <para>
 171                         <classname>\namespace\package\Class_Name</classname> =&gt;
 172                         <filename>/path/to/project/lib/vendor/namespace/package/Class/Name.php</filename>
 173                     </para>
 174                 </listitem>
 175
 176                 <listitem>
 177                     <para>
 178                         <classname>\namespace\package_name\Class_Name</classname> =&gt;
 179                         <filename>/path/to/project/lib/vendor/namespace/package_name/Class/Name.php</filename>
 180                     </para>
 181                 </listitem>
 182             </itemizedlist>
 183         </note>
 184     </sect2>
 185
 186     <sect2 id="zend.loader.load.isreadable">
 187
 188         <title>ファイルが読み込み可能かどうかの確認</title>
 189
 190         <para>
 191             静的メソッド <methodname>Zend_Loader::isReadable($pathname)</methodname>
 192             は、指定した場所にファイルが存在して読み込み可能な場合に
 193             <constant>TRUE</constant>、それ以外の場合に <constant>FALSE</constant> を返します。
 194         </para>
 195
 196         <example id="zend.loader.load.isreadable.example">
 197             <title>isReadable() メソッドの例</title>
 198             <programlisting language="php"><![CDATA[
 199 if (Zend_Loader::isReadable($filename)) {
 200     // $filename で何かをします
 201 }
 202 ]]></programlisting>
 203         </example>
 204
 205         <para>
 206             引数 <code>$filename</code> で、調べたいファイル名を指定します。
 207             ここにはパス情報を含めることもできます。
 208             このメソッドは、<acronym>PHP</acronym> の関数
 209             <ulink url="http://php.net/is_readable"><methodname>is_readable()</methodname></ulink>
 210             のラッパーです。この関数は <code>include_path</code>
 211             を探しませんが、<methodname>Zend_Loader::isReadable()</methodname>
 212             は <code>include_path</code> も検索対象に含めます。
 213         </para>
 214
 215     </sect2>
 216
 217     <sect2 id="zend.loader.load.autoload">
 218
 219         <title>Autoloader の使用法</title>
 220
 221         <para>
 222             <classname>Zend_Loader</classname> クラスには、<acronym>PHP</acronym> の SPL
 223             自動ローダーに登録するためのメソッドが含まれています。そのコールバックメソッドが
 224             <methodname>Zend_Loader::autoload()</methodname> です。利便性を考慮して、
 225             <classname>Zend_Loader</classname> では <methodname>registerAutoload()</methodname> 関数を提供しています。
 226             この関数は、<methodname>autoload()</methodname> メソッドを登録するものです。
 227             <code>spl_autoload</code> 拡張モジュールが使用できない環境の場合は、
 228             <methodname>registerAutoload()</methodname> メソッドは <classname>Zend_Exception</classname> をスローします。
 229         </para>
 230
 231         <example id="zend.loader.load.autoload.example">
 232             <title>自動ローダー用コールバックメソッドの登録例</title>
 233             <programlisting language="php"><![CDATA[
 234 Zend_Loader::registerAutoload();
 235 ]]></programlisting>
 236         </example>
 237
 238         <para>
 239             Zend Framework の autoload コールバックを登録すると、
 240             明示的に読み込まなくても Zend Framework のクラスを参照できるようになります。
 241             <methodname>autoload()</methodname> メソッドは、クラスを参照する際に自動的に
 242             <methodname>Zend_Loader::loadClass()</methodname> を使用します。
 243         </para>
 244
 245         <para>
 246             <classname>Zend_Loader</classname> クラスを継承した場合は、<methodname>registerAutoload()</methodname>
 247             に引数を追加できます。この引数で、どのクラスから
 248             <methodname>autoload()</methodname> メソッドを登録するのかを指定します。
 249         </para>
 250
 251         <example id="zend.loader.load.autoload.example-extended">
 252             <title>autoload コールバックメソッドを継承クラスから登録する例</title>
 253             <para>
 254                 <acronym>PHP</acronym> における静的関数の参照の方法上、
 255                 <methodname>loadClass()</methodname> と <methodname>autoload()</methodname>
 256                 の両方のコードを実装する必要があります。
 257                 そして、<methodname>autoload()</methodname> では
 258                 <methodname>self::loadClass()</methodname> をコールしなければなりません。
 259                 作成する <methodname>autoload()</methodname> メソッドが親クラスに
 260                 <methodname>self::loadClass()</methodname> の処理を任せるのなら、
 261                 サブクラスのメソッドではなく親クラス側の同名のメソッドをコールします。
 262             </para>
 263             <programlisting language="php"><![CDATA[
 264 class My_Loader extends Zend_Loader
 265 {
 266     public static function loadClass($class, $dirs = null)
 267     {
 268         parent::loadClass($class, $dirs);
 269     }
 270
 271     public static function autoload($class)
 272     {
 273         try {
 274             self::loadClass($class);
 275             return $class;
 276         } catch (Exception $e) {
 277             return false;
 278         }
 279     }
 280 }
 281
 282 Zend_Loader::registerAutoload('My_Loader');
 283 ]]></programlisting>
 284         </example>
 285
 286         <para>
 287             autoload コールバックを削除することもできます。
 288             <methodname>registerAutoload()</methodname> にはオプションで 2 番目の引数を指定することができ、
 289             デフォルトでは <constant>TRUE</constant> が設定されるようになっています。
 290             この引数を <constant>FALSE</constant> とすると、
 291             指定したコールバックが SPL の autoload スタックから削除されます。
 292         </para>
 293
 294     </sect2>
 295
 296 </sect1>
 297 <!--
 298 vim:se ts=4 sw=4 et:
 299 -->