documentation/manual/ru/module_specs/Zend_Loader.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.loader.load">
   4
   5     <title>Динамическая загрузка файлов и классов</title>
   6
   7     <para>
   8         Класс <classname>Zend_Loader</classname> включает в себя методы,
   9         помогающие производить динамическую загрузку файлов.
  10     </para>
  11
  12     <tip>
  13         <title>Zend_Loader vs. require_once()</title>
  14         <para>
  15             Методы <classname>Zend_Loader</classname> лучше всего использовать,
  16             когда имя файла для загрузки является переменным - например,
  17             если оно базируется на данных, введенных пользователем,
  18             или аргументе метода.
  19             Если вы загружаете файл или класс, чье имя является постоянным,
  20             то использование <classname>Zend_Loader</classname>
  21             не дает каких-либо преимуществ по сравнению использованием обычных
  22             функций PHP, таких, как
  23             <ulink url="http://php.net/require_once"><code>require_once()</code></ulink>.
  24         </para>
  25     </tip>
  26
  27     <sect2 id="zend.loader.load.file">
  28
  29         <title>Загрузка файлов</title>
  30
  31         <para>
  32             Статический метод <code>Zend_Loader::loadFile()</code> загружает
  33             файл PHP. Загружаемый файл должен содержать код PHP. Метод является
  34             оберткой к PHP-функции
  35             <ulink url="http://php.net/include"><code>include()</code></ulink>.
  36             Этот метод возвращает <constant>FALSE</constant> в случае
  37             неуспеха - например, если требуемый файл не существует.
  38         </para>
  39
  40         <example id="zend.loader.load.file.example">
  41             <title>Пример использования метода loadFile()</title>
  42             <programlisting language="php"><![CDATA[
  43 Zend_Loader::loadFile($filename, $dirs=null, $once=false);
  44 ]]></programlisting>
  45     </example>
  46
  47         <para>
  48             Аргумент <varname>$filename</varname> задает имя файла для загрузки, он
  49             не должен содержать путь к файлу. В целях безопасности производится
  50             проверка <varname>$filename</varname>. <varname>$filename</varname> должен
  51             содержать только алфавитно-цифровые символы, тире ("-"), знак
  52             подчеркивания ("_") и точку ("."). На аргумент <varname>$dirs</varname>
  53             эти ограничения не распространяются.
  54         </para>
  55
  56         <para>
  57             Аргумент <varname>$dirs</varname> задает директории, в которых должен
  58             производиться поиск файла. Если его значение равно
  59             <constant>NULL</constant>, то для поиска используется только
  60             <code>include_path</code>. Если его значение является строкой или
  61             массивом, то файл сначала ищется в данной директории (директориях),
  62             а затем в <code>include_path</code>.
  63         </para>
  64
  65         <para>
  66             Аргумент <varname>$once</varname> является значением булевого типа. Если
  67             равен <constant>TRUE</constant>, то <code>Zend_Loader::loadFile()</code> для
  68             загрузки файла использует PHP-функцию
  69             <ulink url="http://php.net/include"><code>include_once()</code></ulink>,
  70             иначе используется функция <ulink url="http://php.net/include_once"><code>include()</code></ulink>.
  71         </para>
  72
  73     </sect2>
  74
  75     <sect2 id="zend.loader.load.class">
  76
  77         <title>Загрузка классов</title>
  78
  79         <para>
  80             Статический метод <code>Zend_Loader::loadClass($class, $dirs)</code>
  81             загружает файл PHP и затем проверяет наличие требуемого класса.
  82         </para>
  83
  84         <example id="zend.loader.load.class.example">
  85             <title>Пример использования метода loadClass()</title>
  86             <programlisting language="php"><![CDATA[
  87 Zend_Loader::loadClass('Container_Tree',
  88     array(
  89         '/home/production/mylib',
  90         '/home/production/myapp'
  91     )
  92 );
  93 ]]></programlisting>
  94         </example>
  95
  96         <para>
  97             Строка, задающая класс, преобразуется в относительный путь
  98             посредством замены знаков подчеркивания разделителями директорий,
  99             используемыми в вашей ОС, и добавления расширения '.php'. В примере
 100             выше на Windows будет использоваться путь 'Container\\Tree.php'.
 101         </para>
 102
 103         <para>
 104             Если <varname>$dirs</varname> является строкой или массивом, то
 105             <code>Zend_Loader::loadClass()</code> ищет в директориях в
 106             том порядке, в котором они были определены. Загружается первый
 107             найденный файл. Если файл не найден в директориях
 108             <varname>$dirs</varname>, то производится поиск в <code>include_path</code>.
 109         </para>
 110
 111         <para>
 112             Если файл не найден, или класс не существует после загрузки, то
 113             <code>Zend_Loader::loadClass()</code> бросает
 114             исключение <code>Zend_Exception</code>.
 115         </para>
 116
 117         <para>
 118             Для загрузки используется метод
 119             <code>Zend_Loader::loadFile()</code>, поэтому имя класса должно
 120             содержать только алфавитно-цпфровые символы, тире ('-'), знак
 121             подчеркивания ('_') и точку ('.').
 122         </para>
 123
 124     </sect2>
 125
 126     <sect2 id="zend.loader.load.isreadable">
 127
 128         <title>Проверка на возможность чтения из файла</title>
 129
 130         <para>
 131             Статический метод <code>Zend_Loader::isReadable($pathname)</code>
 132             возвращает <constant>TRUE</constant>, если по заданному пути существует файл
 133             и он доступен для чтения, иначе возвращается <constant>FALSE</constant>.
 134         </para>
 135
 136         <example id="zend.loader.load.isreadable.example">
 137             <title>Пример использования метода isReadable()</title>
 138             <programlisting language="php"><![CDATA[
 139 if (Zend_Loader::isReadable($filename)) {
 140     // делаем что-либо с файлом $filename
 141 }
 142 ]]></programlisting>
 143         </example>
 144
 145         <para>
 146             Аргумент <varname>$filename</varname> задает имя файла для проверки. Он
 147             может содержать путь к файлу. Этот метод является оберкой к
 148             PHP-функции
 149             <ulink url="http://php.net/is_readable"><code>is_readable()</code></ulink>.
 150             Метод <code>Zend_Loader::isReadable()</code> производит поиск в
 151             <code>include_path</code>, в то время как <code>is_readable()</code>
 152             этого не делает.
 153         </para>
 154
 155     </sect2>
 156
 157     <sect2 id="zend.loader.load.autoload">
 158
 159         <title>Использование автозагрузчика</title>
 160
 161         <para>
 162             Класс <classname>Zend_Loader</classname> содержит метод, который
 163             можно регистрировать
 164             через автозагрузчик PHP SPL. <code>Zend_Loader::autoload()</code>
 165             является методом обратного вызова. Для удобства
 166             <classname>Zend_Loader</classname> предоставляет метод
 167             <code>registerAutoload()</code> для регистрации
 168             его метода <code>autoload()</code>. Если в используемой среде
 169             PHP отсутствует расширение <code>spl_autoload</code>, то метод
 170             <code>registerAutoload()</code> бросает исключение
 171             <classname>Zend_Exception</classname>.
 172         </para>
 173
 174         <example id="zend.loader.load.autoload.example">
 175             <title>Пример регистрации метода автозагрузки</title>
 176             <programlisting language="php"><![CDATA[
 177 Zend_Loader::registerAutoload();
 178 ]]></programlisting>
 179         </example>
 180
 181         <para>
 182             После регистрации метода автозагрузки вы можете
 183             ссылаться на классы из Zend Framework без их явной загрузки.
 184             Метод <code>autoload()</code> автоматически запускает метод
 185             <code>Zend_Loader::loadClass()</code>, когда вы ссылаетесь на класс.
 186         </para>
 187
 188         <para>
 189             Если вы расширили класс <classname>Zend_Loader</classname>, то
 190             можете передавать методу <code>registerAutoload()</code>
 191             опциональный аргумент для указания
 192             класса, из которого следует регистрировать метод
 193             <code>autoload()</code>.
 194         </para>
 195
 196         <example id="zend.loader.load.autoload.example-extended">
 197             <title>Пример регистрации метода автозагрузки из расширенного класса</title>
 198             <para>
 199                 В силу особенностей семантики статических функций в PHP
 200                 вы должны реализовать код для обоих методов
 201                 <code>loadClass()</code> и <code>autoload()</code>, при этом
 202                 <code>autoload()</code> должен вызывать
 203                 <code>self::loadClass()</code>. Если ваш метод
 204                 <code>autoload()</code> делегирует родительскому классу вызов
 205                 <code>self::loadClass()</code> то будет вызван метод
 206                 родительского класса, не подкласса.
 207             </para>
 208             <programlisting language="php"><![CDATA[
 209 class My_Loader extends Zend_Loader
 210 {
 211     public static function loadClass($class, $dirs = null)
 212     {
 213         parent::loadClass($class, $dirs);
 214     }
 215
 216     public static function autoload($class)
 217     {
 218         try {
 219             self::loadClass($class);
 220             return $class;
 221         } catch (Exception $e) {
 222             return false;
 223         }
 224     }
 225 }
 226
 227 Zend_Loader::registerAutoload('My_Loader');
 228 ]]></programlisting>
 229         </example>
 230
 231         <para>
 232             Регистрацию метода автозагрузки можно отменить.
 233             Метод <code>registerAutoload()</code> имеет опциональный
 234             второй аргумент, его значением по умолчанию является
 235             <constant>TRUE</constant>. Если этот аргумент равен <constant>FALSE</constant>,
 236             то данный метод автозагрузки удаляется из стека SPL.
 237         </para>
 238
 239     </sect2>
 240
 241 </sect1>
 242 <!--
 243 vim:se ts=4 sw=4 et:
 244 -->