repo_zf1/documentation/manual/ja/module_specs/Zend_Loader.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 24249 -->
<sect1 id="zend.loader.load">

    <title>ファイルやクラスの動的な読み込み</title>

    <para>
        <classname>Zend_Loader</classname> クラスは、ファイルを動的に読み込むためのメソッドを提供します。
    </para>

    <tip>
        <title>Zend_Loader 対 require_once()</title>
        <para>
            <classname>Zend_Loader</classname> のメソッドは、読み込みたいファイルの名前が変化する場合に便利です。
            たとえば、ユーザの入力やメソッドの引数などのパラメータに基づいたファイル名を使用する場合などです。
            もし読み込むファイルやクラスの名前が決まっている場合は、
            <ulink url="http://php.net/require_once"><methodname>require_once()</methodname></ulink>
            のような <acronym>PHP</acronym> の関数ではなくあえて <classname>Zend_Loader</classname> を使用するメリットはありません。
        </para>
    </tip>

    <sect2 id="zend.loader.load.file">

        <title>ファイルの読み込み</title>

        <para>
            静的メソッド <methodname>Zend_Loader::loadFile()</methodname>
            は、<acronym>PHP</acronym> ファイルを読み込みます。
            読み込まれるファイルには任意の <acronym>PHP</acronym> コードを含めることができます。
            このメソッドは <acronym>PHP</acronym> 関数
            <ulink url="http://php.net/include"><methodname>include()</methodname></ulink>
            のラッパーで、失敗した場合 (たとえば指定したファイルが存在しないなど)
            には <constant>FALSE</constant> を返します。
        </para>

        <example id="zend.loader.load.file.example">
            <title>loadFile() メソッドの例</title>
            <programlisting language="php"><![CDATA[
Zend_Loader::loadFile($filename, $dirs=null, $once=false);
]]></programlisting>
    </example>

        <para>
            引数 <code>$filename</code> には読み込むファイル名を指定します。
            ここにはパス情報を含めてはいけません。<code>$filename</code>
            に対してはセキュリティチェックが行われます。
            <code>$filename</code> に含めることができるのは英数字、ダッシュ ("-")、
            アンダースコア ("_") あるいはピリオド (".") だけです。
            引数 <code>$dirs</code> にはそのような制限はありません。
        </para>

        <para>
            引数 <code>$dirs</code> にはファイルを探すディレクトリを指定します。
            <constant>NULL</constant> の場合は <property>include_path</property> の中のみを対象とします。
            文字列あるいは配列を指定すると、指定されたディレクトリをまず探した後で、
            それから <property>include_path</property> を探します。
        </para>

        <para>
            引数 <code>$once</code> は論理値です。<constant>TRUE</constant> を指定すると、
            <methodname>Zend_Loader::loadFile()</methodname> は <acronym>PHP</acronym> の関数
            <ulink url="http://php.net/include"><methodname>include_once()</methodname></ulink>
            でファイルを読み込みます。それ以外の場合は
            <ulink url="http://php.net/include_once"><methodname>include()</methodname></ulink>
            を使用します。
        </para>

    </sect2>

    <sect2 id="zend.loader.load.class">

        <title>クラスの読み込み</title>

        <para>
            静的メソッド <methodname>Zend_Loader::loadClass($class, $dirs)</methodname>
            は、<acronym>PHP</acronym> ファイルを読み込んでクラスが存在するかどうかを確かめます。
        </para>

        <example id="zend.loader.load.class.example">
            <title>loadClass() メソッドの例</title>
            <programlisting language="php"><![CDATA[
Zend_Loader::loadClass('Container_Tree',
    array(
        '/home/production/mylib',
        '/home/production/myapp'
    )
);
]]></programlisting>
        </example>

        <para>
            クラスを指定する文字列は、アンダースコアを OS のパス区切り文字に変換して最後に
            '.php' を追加したものとなります。上の例では、Windows 上で
            'Container_Tree' は 'Container\\Tree.php' となります。
        </para>

        <para>
            <code>$dirs</code> に文字列あるいは配列を指定すると、
            <methodname>Zend_Loader::loadClass()</methodname> は指定した順にそのディレクトリを探します。
            そして最初に見つかったファイルを読み込みます。
            ディレクトリ <code>$dirs</code> にファイルがみつからない場合は、
            <acronym>PHP</acronym> の <property>include_path</property> で指定された場所を探します。
        </para>

        <para>
            ファイルが見つからない場合、あるいは読み込んだファイルにクラスが存在しない場合は
            <methodname>Zend_Loader::loadClass()</methodname> は <classname>Zend_Exception</classname>
            をスローします。
        </para>

        <para>
            ファイルの読み込みには <methodname>Zend_Loader::loadFile()</methodname> を使用するので、
            クラス名として指定できるのは
            英数字とハイフン ('-')、アンダースコア ('_') そしてピリオド ('.') だけです。
        </para>

        <!-- TODO : to be translated -->
        <note>
            <title>Loading Classes from PHP Namespaces</title>

            <para>
                Starting in version 1.10.0, Zend Framework now allows loading classes from <acronym>PHP</acronym>
                namespaces. This support follows the same guidelines and implementation as that
                found in the <ulink
                    url="http://groups.google.com/group/php-standards/web/psr-0-final-proposal">PHP
                Framework Interop Group PSR-0</ulink> reference implementation.
            </para>

            <para>
                Under this guideline, the following rules apply:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        Each namespace separator is converted to a
                        <constant>DIRECTORY_SEPARATOR</constant> when loading from the file system.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Each "_" character in the <emphasis>CLASS NAME</emphasis> is converted to a
                        <constant>DIRECTORY_SEPARATOR</constant>.  The "_" character has no special
                        meaning in the namespace.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        The fully-qualified namespace and class is suffixed with ".php" when loading
                        from the file system.
                    </para>
                </listitem>
            </itemizedlist>

            <para>
                As examples:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <classname>\Doctrine\Common\IsolatedClassLoader</classname> =&gt;
                        <filename>/path/to/project/lib/vendor/Doctrine/Common/IsolatedClassLoader.php</filename>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <classname>\namespace\package\Class_Name</classname> =&gt;
                        <filename>/path/to/project/lib/vendor/namespace/package/Class/Name.php</filename>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <classname>\namespace\package_name\Class_Name</classname> =&gt;
                        <filename>/path/to/project/lib/vendor/namespace/package_name/Class/Name.php</filename>
                    </para>
                </listitem>
            </itemizedlist>
        </note>
    </sect2>

    <sect2 id="zend.loader.load.isreadable">

        <title>ファイルが読み込み可能かどうかの確認</title>

        <para>
            静的メソッド <methodname>Zend_Loader::isReadable($pathname)</methodname>
            は、指定した場所にファイルが存在して読み込み可能な場合に
            <constant>TRUE</constant>、それ以外の場合に <constant>FALSE</constant> を返します。
        </para>

        <example id="zend.loader.load.isreadable.example">
            <title>isReadable() メソッドの例</title>
            <programlisting language="php"><![CDATA[
if (Zend_Loader::isReadable($filename)) {
    // $filename で何かをします
}
]]></programlisting>
        </example>

        <para>
            引数 <code>$filename</code> で、調べたいファイル名を指定します。
            ここにはパス情報を含めることもできます。
            このメソッドは、<acronym>PHP</acronym> の関数
            <ulink url="http://php.net/is_readable"><methodname>is_readable()</methodname></ulink>
            のラッパーです。この関数は <property>include_path</property>
            を探しませんが、<methodname>Zend_Loader::isReadable()</methodname>
            は <property>include_path</property> も検索対象に含めます。
        </para>

    </sect2>

    <sect2 id="zend.loader.load.autoload">

        <title>Autoloader の使用法</title>

        <para>
            <classname>Zend_Loader</classname> クラスには、<acronym>PHP</acronym> の SPL
            自動ローダーに登録するためのメソッドが含まれています。そのコールバックメソッドが
            <methodname>Zend_Loader::autoload()</methodname> です。利便性を考慮して、
            <classname>Zend_Loader</classname> では <methodname>registerAutoload()</methodname> 関数を提供しています。
            この関数は、<methodname>autoload()</methodname> メソッドを登録するものです。
            <code>spl_autoload</code> 拡張モジュールが使用できない環境の場合は、
            <methodname>registerAutoload()</methodname> メソッドは <classname>Zend_Exception</classname> をスローします。
        </para>

        <example id="zend.loader.load.autoload.example">
            <title>自動ローダー用コールバックメソッドの登録例</title>
            <programlisting language="php"><![CDATA[
Zend_Loader::registerAutoload();
]]></programlisting>
        </example>

        <para>
            Zend Framework の autoload コールバックを登録すると、
            明示的に読み込まなくても Zend Framework のクラスを参照できるようになります。
            <methodname>autoload()</methodname> メソッドは、クラスを参照する際に自動的に
            <methodname>Zend_Loader::loadClass()</methodname> を使用します。
        </para>

        <para>
            <classname>Zend_Loader</classname> クラスを継承した場合は、<methodname>registerAutoload()</methodname>
            に引数を追加できます。この引数で、どのクラスから
            <methodname>autoload()</methodname> メソッドを登録するのかを指定します。
        </para>

        <example id="zend.loader.load.autoload.example-extended">
            <title>autoload コールバックメソッドを継承クラスから登録する例</title>
            <para>
                <acronym>PHP</acronym> における静的関数の参照の方法上、
                <methodname>loadClass()</methodname> と <methodname>autoload()</methodname>
                の両方のコードを実装する必要があります。
                そして、<methodname>autoload()</methodname> では
                <methodname>self::loadClass()</methodname> をコールしなければなりません。
                作成する <methodname>autoload()</methodname> メソッドが親クラスに
                <methodname>self::loadClass()</methodname> の処理を任せるのなら、
                サブクラスのメソッドではなく親クラス側の同名のメソッドをコールします。
            </para>
            <programlisting language="php"><![CDATA[
class My_Loader extends Zend_Loader
{
    public static function loadClass($class, $dirs = null)
    {
        parent::loadClass($class, $dirs);
    }

    public static function autoload($class)
    {
        try {
            self::loadClass($class);
            return $class;
        } catch (Exception $e) {
            return false;
        }
    }
}

Zend_Loader::registerAutoload('My_Loader');
]]></programlisting>
        </example>

        <para>
            autoload コールバックを削除することもできます。
            <methodname>registerAutoload()</methodname> にはオプションで 2 番目の引数を指定することができ、
            デフォルトでは <constant>TRUE</constant> が設定されるようになっています。
            この引数を <constant>FALSE</constant> とすると、
            指定したコールバックが SPL の autoload スタックから削除されます。
        </para>

    </sect2>

</sect1>
<!--
vim:se ts=4 sw=4 et:
-->