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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <!-- EN-Revision: 20765 -->
   4 <sect1 id="zend.controller.plugins" xmlns:xi="http://www.w3.org/2001/XInclude">
   5     <title>プラグイン</title>
   6
   7     <sect2 id="zend.controller.plugins.introduction">
   8         <title>導入</title>
   9
  10         <para>
  11             コントローラにはプラグイン機構が組み込まれており、
  12             コントローラの処理中にイベントが発生した際にユーザのコードをコールできます。
  13             フロントコントローラは、プラグインブローカにユーザのプラグインを登録します。
  14             そして、イベントメソッドがコールされた際に、
  15             フロントコントローラに登録されているプラグインをプラグインブローカが実行します。
  16         </para>
  17
  18         <para>
  19             イベントメソッドは、抽象クラス
  20             <classname>Zend_Controller_Plugin_Abstract</classname> で定義されています。
  21             ユーザが作成するプラグインクラスは、これを継承させます。
  22         </para>
  23
  24         <itemizedlist>
  25             <listitem>
  26                 <para>
  27                     <methodname>routeStartup()</methodname> は、<classname>Zend_Controller_Front</classname>
  28                     が <link linkend="zend.controller.router">ルータ</link>
  29                     をコールしてルートに対するリクエストの評価を始める前にコールされます。
  30                 </para>
  31             </listitem>
  32
  33             <listitem>
  34                 <para>
  35                     <methodname>routeShutdown()</methodname> は、
  36                     <link linkend="zend.controller.router">ルータ</link>
  37                     がリクエストのルーティングを終了した後にコールされます。
  38                 </para>
  39             </listitem>
  40
  41             <listitem>
  42                 <para>
  43                     <methodname>dispatchLoopStartup()</methodname> は、<classname>Zend_Controller_Front</classname>
  44                     がディスパッチループに入る前にコールされます。
  45                 </para>
  46             </listitem>
  47
  48             <listitem>
  49                 <para>
  50                     <methodname>preDispatch()</methodname> は、アクションが
  51                     <link linkend="zend.controller.dispatcher">ディスパッチャ</link> でディスパッチされる前にコールされます。
  52                     このコールバックは、プロキシやフィルタ的な動作をさせることができます。
  53                     リクエストの内容を変更してディスパッチフラグをリセット
  54                     (<methodname>Zend_Controller_Request_Abstract::setDispatched(false)</methodname> を使用します)
  55                     することで、現在のアクションをスキップさせたり置き換えたりできます。
  56                 </para>
  57             </listitem>
  58
  59             <listitem>
  60                 <para>
  61                     <methodname>postDispatch()</methodname> は、アクションが <link linkend="zend.controller.dispatcher">ディスパッチャ</link>
  62                     でディスパッチされた後にコールされます。
  63                     このコールバックは、プロキシやフィルタ的な動作をさせることができます。
  64                     リクエストの内容を変更してディスパッチフラグをリセット
  65                     (<methodname>Zend_Controller_Request_Abstract::setDispatched(false)</methodname> を使用します)
  66                     することで、新しいディスパッチ先アクションを指定できます。
  67                 </para>
  68             </listitem>
  69
  70             <listitem>
  71                 <para>
  72                     <methodname>dispatchLoopShutdown()</methodname> は、<classname>Zend_Controller_Front</classname>
  73                     がディスパッチループを抜けた後にコールされます。
  74                 </para>
  75             </listitem>
  76         </itemizedlist>
  77     </sect2>
  78
  79     <sect2 id="zend.controller.plugins.writing">
  80         <title>プラグインの書き方</title>
  81
  82         <para>
  83             プラグインクラスを書くには、単に抽象クラス
  84             <classname>Zend_Controller_Plugin_Abstract</classname>
  85             をインクルードしてそれを継承するだけです。
  86         </para>
  87
  88         <programlisting language="php"><![CDATA[
  89 class MyPlugin extends Zend_Controller_Plugin_Abstract
  90 {
  91     // ...
  92 }
  93 ]]></programlisting>
  94
  95         <para>
  96             <classname>Zend_Controller_Plugin_Abstract</classname> には抽象メソッドはありません。
  97             つまり、上に示したイベントメソッドを、
  98             プラグインクラスでかならず実装しなければならないわけではありません。
  99             プラグインの作者が、必要なものだけを選んで実装できます。
 100         </para>
 101
 102         <para>
 103             <classname>Zend_Controller_Plugin_Abstract</classname> では、
 104             リクエストオブジェクトやレスポンスオブジェクトをプラグインから操作できます。
 105             それぞれ、<methodname>getRequest()</methodname> メソッドおよび
 106             <methodname>getResponse()</methodname> メソッドを使用します。
 107         </para>
 108     </sect2>
 109
 110     <sect2 id="zend.controller.plugins.using">
 111         <title>プラグインの使用法</title>
 112         <para>
 113             プラグインクラスを登録するには、
 114             <methodname>Zend_Controller_Front::registerPlugin()</methodname> をコールします。
 115             これは、いつでも行うことができます。
 116             次の例は、コントローラチェインでプラグインを使用する方法を示すものです。
 117         </para>
 118
 119         <programlisting language="php"><![CDATA[
 120 class MyPlugin extends Zend_Controller_Plugin_Abstract
 121 {
 122     public function routeStartup(Zend_Controller_Request_Abstract $request)
 123     {
 124         $this->getResponse()
 125              ->appendBody("<p>routeStartup() がコールされました</p>\n");
 126     }
 127
 128     public function routeShutdown(Zend_Controller_Request_Abstract $request)
 129     {
 130         $this->getResponse()
 131              ->appendBody("<p>routeShutdown() がコールされました</p>\n");
 132     }
 133
 134     public function dispatchLoopStartup(
 135         Zend_Controller_Request_Abstract $request)
 136     {
 137         $this->getResponse()
 138              ->appendBody("<p>dispatchLoopStartup() がコールされました</p>\n");
 139     }
 140
 141     public function preDispatch(Zend_Controller_Request_Abstract $request)
 142     {
 143         $this->getResponse()
 144              ->appendBody("<p>preDispatch() がコールされました</p>\n");
 145     }
 146
 147     public function postDispatch(Zend_Controller_Request_Abstract $request)
 148     {
 149         $this->getResponse()
 150              ->appendBody("<p>postDispatch() がコールされました</p>\n");
 151     }
 152
 153     public function dispatchLoopShutdown()
 154     {
 155         $this->getResponse()
 156              ->appendBody("<p>dispatchLoopShutdown() がコールされました</p>\n");
 157     }
 158 }
 159
 160 $front = Zend_Controller_Front::getInstance();
 161 $front->setControllerDirectory('/path/to/controllers')
 162       ->setRouter(new Zend_Controller_Router_Rewrite())
 163       ->registerPlugin(new MyPlugin());
 164 $front->dispatch();
 165 ]]></programlisting>
 166
 167         <para>
 168             他に何かの出力を行うアクションがなく、ひとつのアクションのみがコールされたとしましょう。
 169             上のプラグインは、次のような出力を行います。
 170         </para>
 171
 172         <programlisting language="php"><![CDATA[
 173 <p>routeStartup() がコールされました</p>
 174 <p>routeShutdown() がコールされました</p>
 175 <p>dispatchLoopStartup() がコールされました</p>
 176 <p>preDispatch() がコールされました</p>
 177 <p>postDispatch() がコールされました</p>
 178 <p>dispatchLoopShutdown() がコールされました</p>
 179 ]]></programlisting>
 180
 181         <note>
 182             <para>
 183                 プラグインは、フロントコントローラの実行時ならいつでも登録できます。
 184                 しかし、プラグインがイベントメソッドを登録しようとしているイベントが終わった後では、
 185                 そのメソッドは実行されません。
 186             </para>
 187         </note>
 188     </sect2>
 189
 190     <sect2 id="zend.controller.plugins.manipulating">
 191         <title>プラグインの取得と操作</title>
 192
 193         <para>
 194             時には、プラグインの登録を解除したりプラグインの情報を取得したいこともあるでしょう。
 195             フロントコントローラには、そのような場合のために次のメソッドが用意されています。
 196         </para>
 197
 198         <itemizedlist>
 199             <listitem>
 200                 <para>
 201                     <methodname>getPlugin($class)</methodname>
 202                     は、指定したクラス名のプラグインを取得します。
 203                     一致するプラグインがない場合は <constant>FALSE</constant> を返します。
 204                     同じクラス名のプラグインが複数登録されている場合は、結果を配列で返します。
 205                 </para>
 206             </listitem>
 207
 208             <listitem>
 209                 <para>
 210                     <methodname>getPlugins()</methodname> は、プラグインスタック全体を取得します。
 211                 </para>
 212             </listitem>
 213
 214             <listitem>
 215                 <para>
 216                     <methodname>unregisterPlugin($plugin)</methodname>
 217                     は、プラグインをスタックから登録解除します。
 218                     パラメータには、プラグインオブジェクト自体かそのクラス名を渡します。
 219                     クラス名を渡すと、一致するプラグインがすべて削除されます。
 220                 </para>
 221             </listitem>
 222         </itemizedlist>
 223     </sect2>
 224
 225     <sect2 id="zend.controller.plugins.standard">
 226         <title>標準の配布パッケージに含まれるプラグイン</title>
 227
 228         <para>
 229             Zend Framework の配布パッケージには、
 230             エラー処理用のプラグインが標準で組み込まれています。
 231         </para>
 232
 233         <xi:include href="Zend_Controller-Plugins-ActionStack.xml" />
 234         <xi:include href="Zend_Controller-Plugins-ErrorHandler.xml" />
 235         <xi:include href="Zend_Controller-Plugins-PutHandler.xml" />
 236     </sect2>
 237 </sect1>
 238 <!--
 239 vim:se ts=4 sw=4 et:
 240 -->