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

<sect1 id="zend.loader.load">

    <title> 动态加载文件和类 </title>

    <para>
        Zend_Loader类可以帮助你动态加载文件。
    </para>

    <tip>
        <title>Zend_Loader vs. require_once()</title>
        <para>
            <code>Zend_Loader</code> 最适合于加载的文件名是变量的情况（例如你要加载的文件的名称来自于用户的输入或者某个方法的参数）。如果你加载的文件名或类名是一个常量（即确定的文件，如/lib/test.php），则使用 <code>Zend_Loader</code> 并不比传统的PHP函数 <ulink url="http://php.net/require_once"><code>require_once()</code></ulink>有什么优势。
        </para>
    </tip>

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

        <title> 加载文件 </title>

        <para>
            静态方法 <code>Zend_Loader::loadFile()</code> 加载PHP文件，被加载的文件可包含任何 PHP 代码。它其实是将PHP的<ulink url="http://php.net/include"><code>include()</code></ulink>函数封装而成的一个静态方法。当包含文件失败时，会抛出异常Zend_Exception，例如指定的文件不存在。
        </para>

        <example id="zend.loader.load.file.example">
            <title>loadFile() 方法范例 </title>
            <programlisting role="php"><![CDATA[
Zend_Loader::loadFile($filename, $dirs=null, $once=false);
]]>
            </programlisting>
    </example>

        <para>
            <code>$filename</code>参数指定需要加载的文件，注意<code>$filename</code>不需要指定任何路径，只需要文件名即可。ZF会对文件作安全性检查。<code>$filename</code> 只能由字母，数字，连接符-,下划线_及英文句号.组成(半角)。<code>$dirs</code>参数则不限，可以使用中文等。
        </para>

        <para>
            <code>$dirs</code> 参数用来指定文件所在目录，可以是一个字符串或者数组。如果为 <code>NULL</code>，则程序将会到系统的 <code>include_path</code> 下寻找文件是否存在（include_path可在php.ini中设置--Haohappy注），如果是字符串或数组，则会到指定的目录下去找，然后才是 <code>include_path</code>。
        </para>

        <para>
            <code>$once</code> 参数为布尔类型，如果为 <code>TRUE</code>，<code>Zend_Loader::loadFile()</code> 使用 PHP 函数 <ulink url="http://php.net/include"><code>include_once()</code></ulink> 加载文件，否则就是 PHP 函数 <ulink url="http://php.net/include_once"><code>include()</code></ulink>。（本参数只能是true或false，两者区别就和include()和include_once()的区别一样。）
        </para>

    </sect2>

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

        <title> 加载类 </title>

        <para>
            静态方法<code>Zend_Loader::loadClass($class, $dirs)</code>用来加载一个 PHP 类文件，该文件名格式为“$className.php”（也就是说加载的文件名称必须和文件中的类同名）。loadClass()会检查文件中的类是否存在。
        </para>

        <example id="zend.loader.load.class.example">
            <title>Example of loadClass() method</title>
            <programlisting role="php"><![CDATA[
Zend_Loader::loadClass('Container_Tree',
    array(
        '/home/production/mylib',
        '/home/production/myapp'
    )
);
]]>
            </programlisting>
        </example>

        <para>
            类名将会根据下划线（作为目录分隔线）对应到相应目录下的PHP文件，并加上'.php'，比如Container_Tree会指向Container\\Tree.php。
        </para>

        <para>
            如果<code>$dirs</code>是一个字符串或数组， <code>Zend_Loader::loadClass()</code>会根据顺序查找相应目录，并加载第一个匹配的文件。如果文件不存在，则会查找 <code>inculde_path</code> 指定的目录。
        </para>

        <para>
            如果文件不存在或者文件中相应的类不存在，那么 <code>Zend_Loader::loadClass()</code> 就会抛出一个 <code>Zend_Exception</code> 异常。
        </para>

        <para>
            <code>Zend_Loader::loadFile()</code> 用来加载文件，所以类名中只能包含字母数字、连接符('-')、下划线('_')和句点('.')。
        </para>

    </sect2>

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

        <title> 判定某个文件是否可读 </title>

        <para>
            静态方法<code>Zend_Loader::isReadable($pathname)</code>判定某个文件是否存在并可读，可读则返回 <code>TRUE</code> ，否则返回 <code>FALSE</code>。
        </para>

        <example id="zend.loader.load.isreadable.example">
            <title>isReadable()示例：</title>
            <programlisting role="php"><![CDATA[
if (Zend_Loader::isReadable($filename)) {
    // do something with $filename
}
]]>
            </programlisting>
        </example>

        <para>
            <code>$filename</code>参数指定了要检查的文件名，包括路径信息。这个方法是将 PHP 函数<ulink url="http://php.net/is_readable"><code>is_readable()</code></ulink>封装而成的，<code>is_readable()</code> 不会自动查找 <code>include_path</code> 下的文件，而 <code>Zend::isReadable()</code> 可以。
        </para>

    </sect2>

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

        <title> 使用 Autoloader</title>

        <para>
            <code>Zend_Loader</code> 类包括一个可以用 PHP SPL autoloader 注册的方法。<code>Zend_Loader::autoload()</code> 是 callback 方法。为方便起见，<code>Zend_Loader</code> 提供 <code>registerAutoload()</code> 函数注册它的 <code>autoload()</code> 方法。如果 <code>spl_autoload</code> 扩展不在你的 PHP 环境中，那么 <code>registerAutoload()</code> 方法将抛出 <code>Zend_Exception</code>。
        </para>

        <example id="zend.loader.load.autoload.example">
            <title> 注册 autoloader callback 方法范例 </title>
            <programlisting role="php"><![CDATA[
Zend_Loader::registerAutoload();
]]>
            </programlisting>
        </example>

        <para>
            注册 Zend Framework autoload callback 后，可以不需要显式加载就可以从 Zend Framework 引用那些类。当应用一个类，<code>autoload()</code> 方法自动地使用 <code>Zend_Loader::loadClass()</code> 。
        </para>

        <para>
            如果继承 <code>Zend_Loader</code> 类，可以给 <code>registerAutoload()</code> 一个可选的参数通过注册一个 <code>autoload()</code> 方法来指定类。
        </para>

        <example id="zend.loader.load.autoload.example-extended">
            <title> 从继承类注册 autoload callback 方法范例 </title>
            <para>
                因为在 PHP 中静态函数引用的语义，你必须实现 <code>loadClass()</code> 和 <code>autoload()</code>，<code>autoload()</code> 必须调用 <code>self::loadClass()</code>。如果 <code>autoload()</code> 方法代表它的父类调用 <code>self::loadClass()</code>，那么它调用在父类中的方法，而不是子类中。
            </para>
            <programlisting role="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 callback，<code>registerAutoload()</code> 有个可选的第二个参数，缺省为 <code>true</code> 。如果这个参数是 <code>false</code>， 那么 autoload callback 从 SPL autoload 栈里 unregistered 掉而不是注册。
        </para>

    </sect2>

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