documentation/manual/ru/module_specs/Zend_Controller-Plugins.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.controller.plugins" xmlns:xi="http://www.w3.org/2001/XInclude">
   4     <title>Плагины</title>
   5
   6     <sect2 id="zend.controller.plugins.introduction">
   7         <title>Введение</title>
   8
   9         <para>
  10             Архитектура контроллеров включает в себя систему плагинов, которая
  11             позволяет добавлять свой код, который будет вызываться при
  12             определенных событиях в процессе жизни контроллера. Фронт-контроллер
  13             использует брокер плагинов (plugin broker) в качестве реестра
  14             пользовательских плагинов, брокер плагинов также обеспечивает вызов
  15             методов событий в каждом плагине, зарегистрированном через
  16             фронт-контроллер.
  17         </para>
  18
  19         <para>
  20             Методы событий определены в абстрактном классе
  21             <classname>Zend_Controller_Plugin_Abstract</classname>, от которого должны
  22             наследовать все пользовательские плагины:
  23         </para>
  24
  25         <itemizedlist>
  26             <listitem>
  27                 <para>
  28                     <code>routeStartup()</code> вызывается до того, как
  29                     <classname>Zend_Controller_Front</classname> вызовет
  30                     <link linkend="zend.controller.router">маршрутизатор</link>
  31                     для сопоставления запроса с зарегистрированными маршрутами.
  32                 </para>
  33             </listitem>
  34
  35             <listitem>
  36                 <para>
  37                     <code>routeShutdown()</code> вызывается после того, как
  38                     <link linkend="zend.controller.router">маршрутизатор</link>
  39                     завершит обработку запроса.
  40                 </para>
  41             </listitem>
  42
  43             <listitem>
  44                 <para>
  45                     <code>dispatchLoopStartup()</code> вызывается до того,
  46                     как <classname>Zend_Controller_Front</classname> войдет в цикл
  47                     диспетчеризации.
  48                 </para>
  49             </listitem>
  50
  51             <listitem>
  52                 <para>
  53                     <code>preDispatch()</code> вызывается до того, как
  54                     <link linkend="zend.controller.dispatcher">диспетчером</link>
  55                     будет вызвано действие. Этот обратный
  56                     вызов (callback) позволяет реализовать поведение посредника
  57                     или фильтра. Через изменение запроса и сброс его
  58                     флага диспетчеризации (методом
  59                     <code>Zend_Controller_Request_Abstract::setDispatched(false)</code>)
  60                     текущее действие может быть пропущено и/или заменено на
  61                     другое.
  62                 </para>
  63             </listitem>
  64
  65             <listitem>
  66                 <para>
  67                     <code>postDispatch()</code> вызывается после того, как
  68                     действие было вызвано
  69                     <link linkend="zend.controller.dispatcher">диспетчером</link>.
  70                     Этот обратный вызов позволяет реализовать поведение фильтра
  71                     или посредника. Через изменение запроса и сброс его
  72                     флага диспетчеризации (методом
  73                     <code>Zend_Controller_Request_Abstract::setDispatched(false)</code>)
  74                     может быть определено новое действие для
  75                     диспетчеризации.
  76                 </para>
  77             </listitem>
  78
  79             <listitem>
  80                 <para>
  81                     <code>dispatchLoopShutdown()</code> вызывается после выхода
  82                     <classname>Zend_Controller_Front</classname> из его цикла
  83                     диспетчеризации.
  84                 </para>
  85             </listitem>
  86         </itemizedlist>
  87     </sect2>
  88
  89     <sect2 id="zend.controller.plugins.writing">
  90         <title>Написание плагинов</title>
  91
  92         <para>
  93             Для того, чтобы написать класс плагина, просто включите и расширьте
  94             абстрактный класс <classname>Zend_Controller_Plugin_Abstract</classname>:
  95         </para>
  96
  97         <programlisting language="php"><![CDATA[
  98 class MyPlugin extends Zend_Controller_Plugin_Abstract
  99 {
 100     // ...
 101 }
 102 ]]></programlisting>
 103
 104         <para>
 105             Ни один из методов класса
 106             <classname>Zend_Controller_Plugin_Abstract</classname> не является
 107             абстрактным, поэтому классы плагинов не обязательно должны
 108             реализовывать все из перечисленных выше методов событий.
 109             Разработчики плагинов могут реализовывать только те методы, которые
 110             требуются для их конкретных нужд.
 111         </para>
 112
 113         <para>
 114             <classname>Zend_Controller_Plugin_Abstract</classname> также делает объекты
 115             запроса и ответа доступными плагинам контроллеров через методы
 116             <code>getRequest()</code> и <code>getResponse()</code>,
 117             соответственно.
 118         </para>
 119     </sect2>
 120
 121     <sect2 id="zend.controller.plugins.using">
 122         <title>Использование плагинов</title>
 123
 124         <para>
 125             Классы плагинов регистрируются через
 126             <code>Zend_Controller_Front::registerPlugin()</code>, их можно
 127             регистрировать в любой момент времени. Следующий пример
 128             демонстрирует использование плагина в цепочке контроллеров:
 129         </para>
 130
 131         <programlisting language="php"><![CDATA[
 132 class MyPlugin extends Zend_Controller_Plugin_Abstract
 133 {
 134     public function routeStartup(Zend_Controller_Request_Abstract $request)
 135     {
 136         $this->getResponse()
 137              ->appendBody("<p>routeStartup() called</p>\n");
 138     }
 139
 140     public function routeShutdown(Zend_Controller_Request_Abstract $request)
 141     {
 142         $this->getResponse()
 143              ->appendBody("<p>routeShutdown() called</p>\n");
 144     }
 145
 146     public function dispatchLoopStartup(Zend_Controller_Request_Abstract $request)
 147     {
 148         $this->getResponse()
 149              ->appendBody("<p>dispatchLoopStartup() called</p>\n");
 150     }
 151
 152     public function preDispatch(Zend_Controller_Request_Abstract $request)
 153     {
 154         $this->getResponse()
 155              ->appendBody("<p>preDispatch() called</p>\n");
 156     }
 157
 158     public function postDispatch(Zend_Controller_Request_Abstract $request)
 159     {
 160         $this->getResponse()
 161              ->appendBody("<p>postDispatch() called</p>\n");
 162     }
 163
 164     public function dispatchLoopShutdown()
 165     {
 166         $this->getResponse()
 167              ->appendBody("<p>dispatchLoopShutdown() called</p>\n");
 168     }
 169 }
 170
 171 $front = Zend_Controller_Front::getInstance();
 172 $front->setControllerDirectory('/path/to/controllers')
 173       ->setRouter(new Zend_Controller_Router_Rewrite())
 174       ->registerPlugin(new MyPlugin());
 175 $front->dispatch();
 176 ]]></programlisting>
 177
 178         <para>
 179             При условии, что вызываемые действия не производят вывод, и
 180             что вызвано только одно действие, с плагином выше должен получиться
 181             следующий вывод:
 182         </para>
 183
 184         <programlisting language="php"><![CDATA[
 185 <p>routeStartup() called</p>
 186 <p>routeShutdown() called</p>
 187 <p>dispatchLoopStartup() called</p>
 188 <p>preDispatch() called</p>
 189 <p>postDispatch() called</p>
 190 <p>dispatchLoopShutdown() called</p>
 191 ]]></programlisting>
 192
 193         <note>
 194             <para>
 195                 Плагины могут регистрироваться в любой точке выполнения
 196                 фронт-контроллера. Однако, если событие, для которого
 197                 плагин имеет зарегистрированный метод события, уже произошло, то
 198                 этот метод не будет запущен.
 199             </para>
 200         </note>
 201     </sect2>
 202
 203     <sect2 id="zend.controller.plugins.manipulating">
 204         <title>Извлечение и работа с плагинами</title>
 205
 206         <para>
 207             Иногда может понадобиться отменить регистрацию плагина или извлечь
 208             его. Следующие методы фронт-контроллера позволяют сделать это:
 209         </para>
 210
 211         <itemizedlist>
 212             <listitem><para>
 213                 <code>getPlugin($class)</code> позволяет извлекать плагин по
 214                 имени класса. Если не найден соответствующий плагин, то
 215                 возвращается false. Если зарегистрировано более одного плагина
 216                 этого класса, то будет возвращен массив.
 217             </para></listitem>
 218
 219             <listitem><para>
 220                 <code>getPlugins()</code> возвращает весь стек плагинов.
 221             </para></listitem>
 222
 223             <listitem><para>
 224                 <code>unregisterPlugin($plugin)</code> производит удаление
 225                 плагина из стека. Вы можете передавать объект плагина или имя
 226                 класса плагина, регистрацию которого вы хотите отменить. Если вы
 227                 передаете имя класса, то будут удалены все плагины этого класса.
 228             </para></listitem>
 229         </itemizedlist>
 230     </sect2>
 231
 232     <sect2 id="zend.controller.plugins.standard">
 233         <title>Плагины, включенные в стандартную поставку</title>
 234
 235         <para>
 236             Zend Framework в его стандартной поставке включает в себя плагин для
 237             обработки ошибок.
 238         </para>
 239
 240         <xi:include href="Zend_Controller-Plugins-ActionStack.xml" />
 241         <xi:include href="Zend_Controller-Plugins-ErrorHandler.xml" />
 242     </sect2>
 243 </sect1>
 244 <!--
 245 vim:se ts=4 sw=4 et:
 246 -->