repo_zf1/documentation/manual/ru/module_specs/Zend_Loader-Autoloader.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.loader.autoloader">
    <title>Автозагрузчик</title>

    <para>
        <classname>Zend_Loader_Autoloader</classname> представляет собой
        комплексное решение для автозагрузки. Он разрабатывался для следующих
        целей:
    </para>

    <itemizedlist>
        <listitem><para>
            Предоставление настоящего автозарузчика пространств имен
            (предыдущие реализации перехватывали все пространства имен подряд).
        </para></listitem>

        <listitem><para>
            Возможность регистрации любых обратных вызовов в качестве
            автозагрузчиков и управления ими как стеком (на момент написания
            данного текста он позволяет обойти некоторые проблемы с
            <code>spl_autoload</code>,
            которые не позволяют заново регистрировать обратные вызовы,
            использующие методы экземпляра).
        </para></listitem>

        <listitem><para>
            Возможность оптимистического сопоставления (optimistic matching)
            пространств имен для более быстрого определения пути к подключаемому
            классу.
        </para></listitem>
    </itemizedlist>

    <para>
        <classname>Zend_Loader_Autoloader</classname> реализован в виде
        синглетона, что делает его доступным из любого места.
        Это дает возможность регистрировать дополнительные автозагрузчики
        в любой момент выполнения, когда это необходимо.
    </para>

    <sect2 id="zend.loader.autoloader.usage">
        <title>Использование автозагрузчика</title>

        <para>
            Когда экземпляр автозагрузчика извлекается в первый раз,
            он регистрирует себя через <code>spl_autoload</code>.
            Вы извлекаете экземпляр, используя метод <code>getInstance()</code>:
        </para>

        <programlisting language="php"><![CDATA[
$autoloader = Zend_Loader_Autoloader::getInstance();
]]></programlisting>

        <para>
            По умолчанию автозагрузчик сконфигурирован с тем, чтобы
            соответствовать пространствам имен "Zend_" и "ZendX_".
            Если у вас есть есть своя библиотека, которая используют
            собственное пространство имен, то вы можете зарегистрировать его
            в автозагрузчике, используя метод <code>registerNamespace()</code>.
            Например, если ваша библиотека представлена префиксом "My_", то вы
            можете сделать это следующим образом:
        </para>

        <programlisting language="php"><![CDATA[
$autoloader->registerNamespace('My_');
]]></programlisting>

        <note>
            <title>Префиксы пространств имен</title>

            <para>
                Обратите внимание, что предыдущий пример использует в
                качестве префикса "My_", а не "My". Это из-за того, что
                <classname>Zend_Loader_Autoloader</classname> задуман как
                загрузчик общего назначения, и не предполагает,
                что префикс пространства имен должен включать в себя знак
                подчеркивания. Если ваше пространство имен классов
                включает в себя знак подчеркивания, то вы должны указывать его
                при регистрации вашего пространства имен.
            </para>
        </note>

        <para>
            Вы можете также регистрировать любые обратные вызовы для
            автозагрузки, опционально с определенным пространством имен (или
            группой пространств имен).
            <classname>Zend_Loader_Autoloader</classname> будет искать
            соответствие им до того, как использовать свой встроенный
            механизм автозагрузки.
        </para>

        <para>
            Например, вам можете захотеть использовать одну или более
            компонент из eZcomponents в своем приложении на основе
            Zend Framework. Для того, чтобы использовать возможности
            eZcomponents по автозагрузке, добавьте его автозагрузчик в стек,
            используя <code>pushAutoloader()</code>:
        </para>

        <programlisting language="php"><![CDATA[
$autoloader->pushAutoloader(array('ezcBase', 'autoload'), 'ezc');
]]></programlisting>

        <para>
            Это говорит автозагрузчику, чтобы он использовал автозагрузчик
            eZcomponents для классов, начинающихся с "ezc".
        </para>

        <para>
            Вы можете использовать метод <code>unshiftAutoloader()</code>
            для добавления автозагрузчика в начало цепочки автозагрузчиков.
        </para>

        <para>
            По умолчанию <classname>Zend_Loader_Autoloader</classname> не
            подавляет ошибки при использовании его внутреннего автозагрузчика,
            который использует <classname>Zend_Loader::loadClass()</classname>.
            В большинстве случаев это именно то, чего вы хотите.
            Тем не менее, могут быть случаи, когда может потребоваться подавлять
            их. Вы можете сделать это, используя метод
            <code>suppressNotFoundWarnings()</code>:
        </para>

        <programlisting language="php"><![CDATA[
$autoloader->suppressNotFoundWarnings(true);
]]></programlisting>

        <para>
            И наконец, иногда может потребоваться, чтобы автозагрузчик загружал
            все пространства имен. Например, библиотеки PEAR не используют
            общего пространства имен, что делает указание отдельных
            пространств имен затруднительным, если используется много компонент
            из PEAR. Вы можете использовать метод
            <code>setFallbackAutoloader()</code>
            для того, чтобы данный автозагрузчик был универсальным для всех
            пространств имен:
        </para>

        <programlisting language="php"><![CDATA[
$autoloader->setFallbackAutoloader(true);
]]></programlisting>
    </sect2>

    <sect2 id="zend.loader.autoloader.interface">
        <title>Итерфейс автозагрузчика</title>

        <para>
            Кроме возможности указывать любые обратные вызовы в качестве
            автозагрузчиков, Zend Framework предоставляет интерфейс,
            который классы автозагрузчиков могут реализовывать -
            <classname>Zend_Loader_Autoloader_Interface</classname>:
        </para>

        <programlisting language="php"><![CDATA[
interface Zend_Loader_Autoloader_Interface
{
    public function autoload($class);
}
]]></programlisting>

        <para>
            Используя этот интерфейс, вы можете передавать экземпляр
            класса методам <classname>Zend_Loader_Autoloader</classname>-а
            <code>pushAutoloader()</code> и <code>unshiftAutoloader()</code>:
        </para>

        <programlisting language="php"><![CDATA[
// Предполагается, что Foo_Autoloader реализует Zend_Loader_Autoloader_Interface:
$foo = new Foo_Autoloader();

$autoloader->pushAutoloader($foo, 'Foo_');
]]></programlisting>
    </sect2>

    <sect2 id="zend.loader.autoloader.reference">
        <title>Справка по автозагрузчику</title>

        <para>
            Ниже приведено руководство по методам, доступным в классе
            <classname>Zend_Loader_Autoloader</classname>.
        </para>

        <table id="zend.loader.autoloader.reference.api">
            <title>Методы Zend_Loader_Autoloader-а</title>
            <tgroup cols="4">
                <thead>
                    <row>
                        <entry>Метод</entry>
                        <entry>Возвращаемое значение</entry>
                        <entry>Параметры</entry>
                        <entry>Описание</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry><code>getInstance()</code></entry>
                        <entry><classname>Zend_Loader_Autoloader</classname></entry>
                        <entry>Нет</entry>
                        <entry><para>
                            Возвращает экземпляр-синглетон класса
                            <classname>Zend_Loader_Autoloader</classname>.
                            При первом извлечении он регистрирует
                            себя через <code>spl_autoload</code>.
                            Этот метод является статическим.
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>resetInstance()</code></entry>
                        <entry><code>void</code></entry>
                        <entry>Нет</entry>
                        <entry><para>
                            Устанавливает состояние экземпляра-синглетона
                            <classname>Zend_Loader_Autoloader</classname>
                            в его исходное состояние, отменяя регистрацию
                            всех обратных вызовов и всех зарегистрированных
                            пространств имен.
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>autoload($class)</code></entry>
                        <entry><code>string|false</code></entry>
                        <entry><itemizedlist>
                            <listitem><para>
                                <varname>$class</varname>, <emphasis>обязательный</emphasis>.
                                Строка с именем класса для загрузки.
                            </para></listitem>
                        </itemizedlist></entry>
                        <entry><para>
                            Пытается определить путь к файлу по имени класса
                            и загрузить его.
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>setDefaultAutoloader($callback)</code></entry>
                        <entry><classname>Zend_Loader_Autoloader</classname></entry>
                        <entry><itemizedlist>
                            <listitem><para>
                                <varname>$callback</varname>, <emphasis>обязательный</emphasis>.
                            </para></listitem>
                        </itemizedlist></entry>
                        <entry><para>
                            Указывает альтернативный обратный вызов для
                            применения в используемой по умолчанию реализации
                            автозагрузчика.
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>getDefaultAutoloader()</code></entry>
                        <entry><code>callback</code></entry>
                        <entry>Нет</entry>
                        <entry><para>
                            Возвращает используемую по умолчанию реализацию
                            автозагрузчика; по умолчанию это
                            <classname>Zend_Loader::loadClass()</classname>.
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>setAutoloaders(array $autoloaders)</code></entry>
                        <entry><classname>Zend_Loader_Autoloader</classname></entry>
                        <entry><itemizedlist>
                            <listitem><para>
                                <varname>$autoloaders</varname>, <emphasis>обязательный</emphasis>.
                            </para></listitem>
                        </itemizedlist></entry>
                        <entry><para>
                            Устанавливает список автозагрузчиков для
                            использования в стеке автозагрузчиков.
                            Каждый элемент в массиве автозагрузчиков должен быть
                            обратным вызовом PHP.
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>getAutoloaders()</code></entry>
                        <entry><type>Array</type></entry>
                        <entry>Нет</entry>
                        <entry><para>
                            Возвращает внутренний стек автозагрузчиков.
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>getNamespaceAutoloaders($namespace)</code></entry>
                        <entry><type>Array</type></entry>
                        <entry><itemizedlist>
                            <listitem><para>
                                <varname>$namespace</varname>, <emphasis>обязательный</emphasis>
                            </para></listitem>
                        </itemizedlist></entry>
                        <entry><para>
                            Извлекает все автозагрузчики, которые были
                            зарегистрированы для загрузки данного
                            пространства имен.
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>registerNamespace($namespace)</code></entry>
                        <entry><classname>Zend_Loader_Autoloader</classname></entry>
                        <entry><itemizedlist>
                            <listitem><para>
                                <varname>$namespace</varname>, <emphasis>обязательный</emphasis>.
                            </para></listitem>
                        </itemizedlist></entry>
                        <entry><para>
                            Регистрирует одно или более пространств имен с
                            используемым по умолчанию автозагрузчиком.
                            Если <varname>$namespace</varname> является строкой,
                            то она регистрируется как пространство имен;
                            если же массив строк, то все они
                            регистрируются как пространства имен.
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>unregisterNamespace($namespace)</code></entry>
                        <entry><classname>Zend_Loader_Autoloader</classname></entry>
                        <entry><itemizedlist>
                            <listitem><para>
                                <varname>$namespace</varname>, <emphasis>обязательный</emphasis>.
                            </para></listitem>
                        </itemizedlist></entry>
                        <entry><para>
                            Отменяет регистрацию одного или более пространств
                            имен из используемого по умолчанию автозагрузчика.
                            Если <varname>$namespace</varname> является строкой,
                            то отменяется регистрация пространства имен
                            под этим именем;
                            если это массив строк, то отменяются
                            регистрации всех пространств имен в этом массиве.
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>getRegisteredNamespace()</code></entry>
                        <entry><type>Array</type></entry>
                        <entry>Нет</entry>
                        <entry><para>
                            Возвращает массив пространств имен,
                            зарегистрированных с используемым по умолчанию
                            автозагрузчиком.
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>suppressNotFoundWarnings($flag = null)</code></entry>
                        <entry><code>boolean|Zend_Loader_Autoloader</code></entry>
                        <entry><itemizedlist>
                            <listitem><para>
                                <varname>$flag</varname>, <emphasis>опциональный</emphasis>.
                            </para></listitem>
                        </itemizedlist></entry>
                        <entry><para>
                            Устанавливает или возвращает значение флага,
                            который используется для указания того, должна ли
                            применяемая по умолчанию реализация автозагрузчика
                            подавлять предупреждение "файл не найден"
                            ("file not found"). Если ему не передаются аргументы
                            или передано значение null, то он возвращает
                            булево значение, показывающее статус флага.
                            Если же передано булево значение, то флаг
                            принимает данное значение и возвращается
                            экземпляр автозагрузчика (для возможности
                            использования method chaining).
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>setFallbackAutoloader($flag)</code></entry>
                        <entry><classname>Zend_Loader_Autoloader</classname></entry>
                        <entry><itemizedlist>
                            <listitem><para>
                                <varname>$flag</varname>, <emphasis>обязательный</emphasis>.
                            </para></listitem>
                        </itemizedlist></entry>
                        <entry><para>
                            Устанавливает значение флага, который используется
                            для указания того, должен или нет применяемый по
                            умолчанию автозагрузчик использоваться в качестве
                            обратного вызова или универсального автозагрузчика
                            для всех пространств имен.
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>isFallbackAutoloader()</code></entry>
                        <entry><type>Boolean</type></entry>
                        <entry>Нет</entry>
                        <entry><para>
                            Возвращает значение флага, который используется для
                            указания того, должен или нет применяемый по
                            умолчанию автозагрузчик использоваться в качестве
                            обратного вызова или универсального автозагрузчика
                            для всех пространств имен.
                            По умолчанию его значение равно false.
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>getClassAutoloaders($class)</code></entry>
                        <entry><type>Array</type></entry>
                        <entry><itemizedlist>
                            <listitem><para>
                                <varname>$class</varname>, <emphasis>обязательный</emphasis>.
                            </para></listitem>
                        </itemizedlist></entry>
                        <entry><para>
                            Возвращает список автозагрузчиков, которые могут
                            соответствовать данному классу. Если нет ни одного
                            подходящего автозагрузчика, то возвращаются все
                            глобальные (без привязки к пространству имен)
                            автозагрузчики.
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>unshiftAutoloader($callback, $namespace = '')</code></entry>
                        <entry><classname>Zend_Loader_Autoloader</classname></entry>
                        <entry><itemizedlist>
                            <listitem><para>
                                <varname>$callback</varname>, <emphasis>обязательный</emphasis>.
                                Обратный вызов PHP
                            </para></listitem>

                            <listitem><para>
                                <varname>$namespace</varname>, <emphasis>опциональный</emphasis>.
                                Строка с префиксом имен классов, используемым в
                                качестве пространства имен.
                            </para></listitem>
                        </itemizedlist></entry>
                        <entry><para>
                            Добавляет конкретную реализацию автозагрузчика
                            в начало внутреннего стека автозагрузчиков. Если
                            было передано пространство имен, то оно будет
                            использовано для оптимистического сопоставления
                            (optimistic matching), иначе автозагрузчик будет
                            использоваться в качестве глобального.
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>pushAutoloader($callback, $namespace = '')</code></entry>
                        <entry><classname>Zend_Loader_Autoloader</classname></entry>
                        <entry><itemizedlist>
                            <listitem><para>
                                <varname>$callback</varname>, <emphasis>обязательный</emphasis>.
                                Обратный вызов PHP
                            </para></listitem>

                            <listitem><para>
                                <varname>$namespace</varname>, <emphasis>опциональный</emphasis>.
                                Строка с префиксом имен классов, используемым в
                                качестве пространства имен.
                            </para></listitem>
                        </itemizedlist></entry>
                        <entry><para>
                            Добавляет конкретную реализацию автозагрузчика
                            в конец внутреннего стека автозагрузчиков. Если
                            было передано пространство имен, то оно будет
                            использовано для оптимистического сопоставления
                            (optimistic matching), иначе автозагрузчик будет
                            использоваться в качестве глобального.
                        </para></entry>
                    </row>

                    <row>
                        <entry><code>removeAutoloader($callback, $namespace = '')</code></entry>
                        <entry><classname>Zend_Loader_Autoloader</classname></entry>
                        <entry><itemizedlist>
                            <listitem><para>
                                <varname>$callback</varname>, <emphasis>обязательный</emphasis>.
                                Обратный вызов PHP
                            </para></listitem>

                            <listitem><para>
                                <varname>$namespace</varname>, <emphasis>опциональный</emphasis>.
                                Строка, представляющая собой префикс имен
                                классов (используемый в качестве пространства
                                имен) или массив строк с префиксами.
                            </para></listitem>
                        </itemizedlist></entry>
                        <entry><para>
                            Удаляет конкретную реализацию автозагрузчика из
                            внутреннего стека автозагрузчиков.
                            Если предоставлено пространство (пространства) имен,
                            то обратный вызов будет удален только для данного
                            пространства (пространств) имен.
                        </para></entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
    </sect2>
</sect1>