documentation/manual/en/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>Plugins</title>
   5
   6     <sect2 id="zend.controller.plugins.introduction">
   7         <title>Introduction</title>
   8
   9         <para>
  10             The controller architecture includes a plugin system that allows
  11             user code to be called when certain events occur in the controller
  12             process lifetime. The front controller uses a plugin broker as a
  13             registry for user plugins, and the plugin broker ensures that event
  14             methods are called on each plugin registered with the front
  15             controller.
  16         </para>
  17
  18         <para>
  19             The event methods are defined in the abstract class
  20             <classname>Zend_Controller_Plugin_Abstract</classname>, from which user plugin
  21             classes inherit:
  22         </para>
  23
  24         <itemizedlist>
  25             <listitem>
  26                 <para>
  27                     <methodname>routeStartup()</methodname> is called before
  28                     <classname>Zend_Controller_Front</classname> calls on <link
  29                         linkend="zend.controller.router">the router</link>
  30                     to evaluate the request against the registered routes.
  31                 </para>
  32             </listitem>
  33
  34             <listitem>
  35                 <para>
  36                     <methodname>routeShutdown()</methodname> is called after <link
  37                         linkend="zend.controller.router">the router</link>
  38                     finishes routing the request.
  39                 </para>
  40             </listitem>
  41
  42             <listitem>
  43                 <para>
  44                     <methodname>dispatchLoopStartup()</methodname> is called before
  45                     <classname>Zend_Controller_Front</classname> enters its dispatch loop.
  46                 </para>
  47             </listitem>
  48
  49             <listitem>
  50                 <para>
  51                     <methodname>preDispatch()</methodname> is called before an action is
  52                     dispatched by <link linkend="zend.controller.dispatcher">the
  53                         dispatcher</link>. This callback allows for proxy or
  54                     filter behavior. By altering the request and resetting its
  55                     dispatched flag (via
  56                     <methodname>Zend_Controller_Request_Abstract::setDispatched(false)</methodname>),
  57                     the current action may be skipped and/or replaced.
  58                 </para>
  59             </listitem>
  60
  61             <listitem>
  62                 <para>
  63                     <methodname>postDispatch()</methodname> is called after an action is
  64                     dispatched by <link linkend="zend.controller.dispatcher">the
  65                         dispatcher</link>. This callback allows for proxy or
  66                     filter behavior. By altering the request and resetting its
  67                     dispatched flag (via
  68                     <methodname>Zend_Controller_Request_Abstract::setDispatched(false)</methodname>),
  69                     a new action may be specified for dispatching.
  70                 </para>
  71             </listitem>
  72
  73             <listitem>
  74                 <para>
  75                     <methodname>dispatchLoopShutdown()</methodname> is called after
  76                     <classname>Zend_Controller_Front</classname> exits its dispatch loop.
  77                 </para>
  78             </listitem>
  79         </itemizedlist>
  80     </sect2>
  81
  82     <sect2 id="zend.controller.plugins.writing">
  83         <title>Writing Plugins</title>
  84
  85         <para>
  86             In order to write a plugin class, simply include and extend the
  87             abstract class <classname>Zend_Controller_Plugin_Abstract</classname>:
  88         </para>
  89
  90         <programlisting language="php"><![CDATA[
  91 class MyPlugin extends Zend_Controller_Plugin_Abstract
  92 {
  93     // ...
  94 }
  95 ]]></programlisting>
  96
  97         <para>
  98             None of the methods of <classname>Zend_Controller_Plugin_Abstract</classname>
  99             are abstract, and this means that plugin classes are not forced to
 100             implement any of the available event methods listed above. Plugin
 101             writers may implement only those methods required by their
 102             particular needs.
 103         </para>
 104
 105         <para>
 106             <classname>Zend_Controller_Plugin_Abstract</classname> also makes the request
 107             and response objects available to controller plugins via the
 108             <methodname>getRequest()</methodname> and <methodname>getResponse()</methodname>
 109             methods, respectively.
 110         </para>
 111     </sect2>
 112
 113     <sect2 id="zend.controller.plugins.using">
 114         <title>Using Plugins</title>
 115
 116         <para>
 117             Plugin classes are registered with
 118             <methodname>Zend_Controller_Front::registerPlugin()</methodname>, and may be
 119             registered at any time. The following snippet illustrates how a
 120             plugin may be used in the controller chain:
 121         </para>
 122
 123         <programlisting language="php"><![CDATA[
 124 class MyPlugin extends Zend_Controller_Plugin_Abstract
 125 {
 126     public function routeStartup(Zend_Controller_Request_Abstract $request)
 127     {
 128         $this->getResponse()
 129              ->appendBody("<p>routeStartup() called</p>\n");
 130     }
 131
 132     public function routeShutdown(Zend_Controller_Request_Abstract $request)
 133     {
 134         $this->getResponse()
 135              ->appendBody("<p>routeShutdown() called</p>\n");
 136     }
 137
 138     public function dispatchLoopStartup(
 139         Zend_Controller_Request_Abstract $request)
 140     {
 141         $this->getResponse()
 142              ->appendBody("<p>dispatchLoopStartup() called</p>\n");
 143     }
 144
 145     public function preDispatch(Zend_Controller_Request_Abstract $request)
 146     {
 147         $this->getResponse()
 148              ->appendBody("<p>preDispatch() called</p>\n");
 149     }
 150
 151     public function postDispatch(Zend_Controller_Request_Abstract $request)
 152     {
 153         $this->getResponse()
 154              ->appendBody("<p>postDispatch() called</p>\n");
 155     }
 156
 157     public function dispatchLoopShutdown()
 158     {
 159         $this->getResponse()
 160              ->appendBody("<p>dispatchLoopShutdown() called</p>\n");
 161     }
 162 }
 163
 164 $front = Zend_Controller_Front::getInstance();
 165 $front->setControllerDirectory('/path/to/controllers')
 166       ->setRouter(new Zend_Controller_Router_Rewrite())
 167       ->registerPlugin(new MyPlugin());
 168 $front->dispatch();
 169 ]]></programlisting>
 170
 171         <para>
 172             Assuming that no actions called emit any output, and only one action
 173             is called, the functionality of the above plugin would still create
 174             the following output:
 175         </para>
 176
 177         <programlisting language="php"><![CDATA[
 178 <p>routeStartup() called</p>
 179 <p>routeShutdown() called</p>
 180 <p>dispatchLoopStartup() called</p>
 181 <p>preDispatch() called</p>
 182 <p>postDispatch() called</p>
 183 <p>dispatchLoopShutdown() called</p>
 184 ]]></programlisting>
 185
 186         <note>
 187             <para>
 188                 Plugins may be registered at any time during the front
 189                 controller execution. However, if an event has passed for which
 190                 the plugin has a registered event method, that method will not
 191                 be triggered.
 192             </para>
 193         </note>
 194     </sect2>
 195
 196     <sect2 id="zend.controller.plugins.manipulating">
 197         <title>Retrieving and Manipulating Plugins</title>
 198
 199         <para>
 200             On occasion, you may need to unregister or retrieve a plugin. The
 201             following methods of the front controller allow you to do so:
 202         </para>
 203
 204         <itemizedlist>
 205             <listitem>
 206                 <para>
 207                     <methodname>getPlugin($class)</methodname> allows you to retrieve a
 208                     plugin by class name. If no plugins match, it returns
 209                     <constant>FALSE</constant>. If more than one plugin of that class
 210                     is registered, it returns an array.
 211                 </para>
 212             </listitem>
 213
 214             <listitem>
 215                 <para>
 216                     <methodname>getPlugins()</methodname> retrieves the entire plugin stack.
 217                 </para>
 218             </listitem>
 219
 220             <listitem>
 221                 <para>
 222                     <methodname>unregisterPlugin($plugin)</methodname> allows you to remove
 223                     a plugin from the stack. You may pass a plugin object, or
 224                     the class name of the plugin you wish to unregister. If you
 225                     pass the class name, any plugins of that class will be
 226                     removed.
 227                 </para>
 228             </listitem>
 229         </itemizedlist>
 230     </sect2>
 231
 232     <sect2 id="zend.controller.plugins.standard">
 233         <title>Plugins Included in the Standard Distribution</title>
 234
 235         <para>
 236             Zend Framework includes a plugin for error handling in its standard
 237             distribution.
 238         </para>
 239
 240         <xi:include href="Zend_Controller-Plugins-ActionStack.xml" />
 241         <xi:include href="Zend_Controller-Plugins-ErrorHandler.xml" />
 242         <xi:include href="Zend_Controller-Plugins-PutHandler.xml" />
 243     </sect2>
 244 </sect1>
 245 <!--
 246 vim:se ts=4 sw=4 et:
 247 -->