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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <!-- EN-Revision: 20765 -->
   4 <sect1 id="zend.controller.router" xmlns:xi="http://www.w3.org/2001/XInclude">
   5     <title>標準のルータ</title>
   6
   7     <sect2 id="zend.controller.router.introduction">
   8         <title>導入</title>
   9
  10         <para>
  11             <classname>Zend_Controller_Router_Rewrite</classname> は、標準のルータです。
  12             ルーティングとは、<acronym>URI</acronym> (ベース <acronym>URL</acronym> から取得した <acronym>URI</acronym> の一部)
  13             を展開し、どのコントローラのどのアクションが
  14             リクエストを処理するのかを決める処理のことです。
  15             モジュールやコントローラ、アクション、そしてその他のパラメータが
  16             <classname>Zend_Controller_Request_Http</classname> オブジェクトにまとめられます。
  17             このオブジェクトを処理するのが <classname>Zend_Controller_Dispatcher_Standard</classname> です。
  18             ルーティングが行われるのは一度だけ、すなわちリクエストを最初に受け取ってから
  19             最初のコントローラに処理が渡される際だけです。
  20         </para>
  21
  22         <para>
  23             <classname>Zend_Controller_Router_Rewrite</classname> は、mod_rewrite 風の機能を
  24             <acronym>PHP</acronym> だけで実現できるように設計されています。
  25             この処理は Ruby on Rails のルーティングを多少参考にしており、
  26             ウェブサーバの <acronym>URL</acronym> 書き換えに関する前提知識を必要としません。
  27             以下の単純な mod_rewrite ルール (のいずれか) で動作するように設計されています。
  28         </para>
  29
  30         <programlisting language="php"><![CDATA[
  31 RewriteEngine on
  32 RewriteRule !\.(js|ico|gif|jpg|png|css|html)$ index.php
  33 ]]></programlisting>
  34
  35         <para>
  36             あるいは (推奨)
  37         </para>
  38
  39         <programlisting language="php"><![CDATA[
  40 RewriteEngine On
  41 RewriteCond %{REQUEST_FILENAME} -s [OR]
  42 RewriteCond %{REQUEST_FILENAME} -l [OR]
  43 RewriteCond %{REQUEST_FILENAME} -d
  44 RewriteRule ^.*$ - [NC,L]
  45 RewriteRule ^.*$ index.php [NC,L]
  46 ]]></programlisting>
  47
  48         <para>
  49             Rewrite ルータを <acronym>IIS</acronym> ウェブサーバ (バージョン &lt;= 7.0) で使用するには
  50             <ulink url="http://www.isapirewrite.com">Isapi_Rewrite</ulink>
  51             を Isapi 拡張モジュールとしてインストールします。そして次のようなルールを記述します。
  52         </para>
  53
  54         <programlisting language="php"><![CDATA[
  55 RewriteRule ^[\w/\%]*(?:\.(?!(?:js|ico|gif|jpg|png|css|html)$)[\w\%]*$)? /index.php [I]
  56 ]]></programlisting>
  57
  58         <note>
  59             <title>IIS Isapi_Rewrite</title>
  60
  61             <para>
  62                 <acronym>IIS</acronym> を使用すると、<varname>$_SERVER['REQUEST_URI']</varname>
  63                 が存在しないか空の文字列に設定されます。このような場合、
  64                 <classname>Zend_Controller_Request_Http</classname> は
  65                 <varname>$_SERVER['HTTP_X_REWRITE_URL']</varname> の値を使用します。これは
  66                 <classname>Isapi_Rewrite</classname> 拡張モジュールが設定します。
  67             </para>
  68         </note>
  69
  70         <para>
  71             <acronym>IIS</acronym> 7.0 ではネイティブの <acronym>URL</acronym> リライトモジュールが登場しました。
  72             次のように設定して使います。
  73         </para>
  74
  75         <programlisting language="xml"><![CDATA[
  76 <?xml version="1.0" encoding="UTF-8"?>
  77 <configuration>
  78      <system.webServer>
  79          <rewrite>
  80              <rules>
  81                  <rule name="Imported Rule 1" stopProcessing="true">
  82                      <match url="^.*$" />
  83                      <conditions logicalGrouping="MatchAny">
  84                          <add input="{REQUEST_FILENAME}"
  85                              matchType="IsFile" pattern=""
  86                              ignoreCase="false" />
  87                          <add input="{REQUEST_FILENAME}"
  88                              matchType="IsDirectory"
  89                              pattern="" ignoreCase="false" />
  90                      </conditions>
  91                      <action type="None" />
  92                  </rule>
  93                  <rule name="Imported Rule 2" stopProcessing="true">
  94                      <match url="^.*$" />
  95                      <action type="Rewrite" url="index.php" />
  96                  </rule>
  97              </rules>
  98          </rewrite>
  99      </system.webServer>
 100 </configuration>
 101 ]]></programlisting>
 102
 103         <para>
 104             Lighttpd の場合は、次のようなルールを使用します。
 105         </para>
 106
 107         <programlisting language="lighttpd"><![CDATA[
 108 url.rewrite-once = (
 109     ".*\?(.*)$" => "/index.php?$1",
 110     ".*\.(js|ico|gif|jpg|png|css|html)$" => "$0",
 111     "" => "/index.php"
 112 )
 113 ]]></programlisting>
 114     </sect2>
 115
 116     <sect2 id="zend.controller.router.usage">
 117         <title>ルータの使用法</title>
 118
 119         <para>
 120             Rewrite ルータを適切に使用するには、まずそのインスタンスを作成し、
 121             次にユーザ定義のルーティングを追加し、それをコントローラに注入しなければなりません。
 122             以下にコードの例を示します。
 123         </para>
 124
 125         <programlisting language="php"><![CDATA[
 126 // ルータを作成します
 127
 128 $router = $ctrl->getRouter(); // デフォルトで rewrite ルータを返します
 129 $router->addRoute(
 130     'user',
 131     new Zend_Controller_Router_Route('user/:username',
 132                                      array('controller' => 'user',
 133                                            'action' => 'info'))
 134 );
 135 ]]></programlisting>
 136     </sect2>
 137
 138     <sect2 id="zend.controller.router.basic">
 139         <title>基本的な RewriteRouter の操作法</title>
 140
 141         <para>
 142             RewriteRouter で最も重要なのが、ユーザ定義のルーティングです。
 143             これは、RewriteRouter の addRoute メソッドをコールして追加します。
 144             このメソッドに、<classname>Zend_Controller_Router_Route_Interface</classname>
 145             を実装したクラスの新しいインスタンスを渡します。
 146         </para>
 147
 148         <programlisting language="php"><![CDATA[
 149 $router->addRoute('user',
 150                   new Zend_Controller_Router_Route('user/:username'));
 151 ]]></programlisting>
 152
 153         <para>
 154             Rewrite ルータには、6 種類の基本的なルーティング方式があります
 155             (そのうちのひとつは特別なものです)。
 156         </para>
 157
 158         <itemizedlist mark="opencircle">
 159             <listitem>
 160                 <para>
 161                     <link
 162                         linkend="zend.controller.router.routes.standard">Zend_Controller_Router_Route</link>
 163                 </para>
 164             </listitem>
 165
 166             <listitem>
 167                 <para>
 168                     <link
 169                         linkend="zend.controller.router.routes.static">Zend_Controller_Router_Route_Static</link>
 170                 </para>
 171             </listitem>
 172
 173             <listitem>
 174                 <para>
 175                     <link
 176                         linkend="zend.controller.router.routes.regex">Zend_Controller_Router_Route_Regex</link>
 177                 </para>
 178             </listitem>
 179
 180             <listitem>
 181                 <para>
 182                     <link
 183                         linkend="zend.controller.router.routes.hostname">Zend_Controller_Router_Route_Hostname</link>
 184                 </para>
 185              </listitem>
 186
 187             <listitem>
 188                 <para>
 189                     <link
 190                         linkend="zend.controller.router.routes.chain">Zend_Controller_Router_Route_Chain</link>
 191                 </para>
 192             </listitem>
 193
 194             <listitem>
 195                 <para>
 196                     <link
 197                         linkend="zend.controller.router.default-routes">Zend_Controller_Router_Rewrite</link>
 198                     *
 199                 </para>
 200             </listitem>
 201         </itemizedlist>
 202
 203         <para>
 204             これらのルーティングは、チェインやユーザ定義のルーティング方式を作成する際に何度も使用します。
 205             任意の設定でお好みの数のルーティングを使用できますが、
 206             Module ルートだけは例外です。これを使用するのは一度だけで、
 207             もっとも汎用的なルート (デフォルト) として使用します。
 208             個々のルーティング方式については、後ほど詳細に説明します。
 209         </para>
 210
 211         <para>
 212             addRoute への最初のパラメータはルートの名前です。
 213             これを使用して、ルータがルートを処理します。
 214             たとえば <acronym>URL</acronym> の生成などに使用します。
 215             二番目のパラメータはルート自身となります。
 216         </para>
 217
 218         <note>
 219             <para>
 220                 ルート名のもっとも一般的な使用例は、
 221                 <classname>Zend_View</classname> の url ヘルパーです。
 222             </para>
 223
 224             <programlisting language="php"><![CDATA[
 225 <a href=
 226 "<?php echo $this->url(array('username' => 'martel'), 'user') ?>">Martel</a>
 227 ]]></programlisting>
 228
 229             <para>
 230                 これは <filename>user/martel</filename> へのリンクとなります。
 231             </para>
 232         </note>
 233
 234         <para>
 235             ルーティング処理は、定義されたすべてのルートから
 236             リクエスト <acronym>URI</acronym> にマッチする定義を探すことによって行います。
 237             マッチするものが見つかれば、ルートのインスタンスから変数の値が返され、
 238             それを Zend_Controller_Request オブジェクトに注入します。
 239             これを、後にディスパッチャやユーザが作成したコントローラで使用します。
 240             マッチするものが見つからない場合は、チェイン内の次のルートを調べます。
 241         </para>
 242
 243         <para>
 244             どのルートがマッチしたかを知りたい場合は
 245             <methodname>getCurrentRouteName()</methodname> メソッドを使用します。
 246             これは、ルートをルータに登録する際に使用した識別子を返します。
 247             ルートオブジェクトそのものを取得したい場合は
 248             <methodname>getCurrentRoute()</methodname> を使用します。
 249         </para>
 250
 251         <note>
 252             <title>定義の順番</title>
 253             <para>
 254                 一番最後にマッチしたルートが適用されるので、
 255                 汎用的なルートは最初に定義するようにしましょう。
 256             </para>
 257         </note>
 258
 259         <note>
 260             <title>返される値</title>
 261             <para>
 262                 ルーティングの結果返される値は、<acronym>URL</acronym> パラメータあるいは
 263                 ユーザ定義のルータのデフォルト値です。これらの値は、後ほど
 264                 <methodname>Zend_Controller_Request::getParam()</methodname> あるいは
 265                 <methodname>Zend_Controller_Action::_getParam()</methodname>
 266                 メソッドでアクセスできます。
 267             </para>
 268         </note>
 269
 270         <para>
 271             ルートで使用される変数のうち、'module'、'controller' および 'action'
 272             の 3 つは特別な扱いとなります。これらの特殊変数は、<classname>Zend_Controller_Dispatcher</classname>
 273             がディスパッチ先のコントローラとアクションを決定するために使用されます。
 274         </para>
 275
 276         <note>
 277             <title>特殊変数</title>
 278             <para>
 279                 これらの特殊変数の名前を変更することもできます。その場合は
 280                 <classname>Zend_Controller_Request_Http</classname> の
 281                 <methodname>setControllerKey()</methodname> メソッドや
 282                 <methodname>setActionKey()</methodname> メソッドを使用します。
 283             </para>
 284         </note>
 285
 286     </sect2>
 287
 288     <sect2 id="zend.controller.router.default-routes">
 289         <title>デフォルトのルート</title>
 290
 291         <para>
 292             <classname>Zend_Controller_Router_Rewrite</classname> がデフォルトのルートとして設定されています。
 293             これは <filename>controller/action</filename> 形式の <acronym>URI</acronym> にマッチします。
 294             さらに、パス要素の最初の部分にモジュール名を指定できます。つまり
 295             <filename>module/controller/action</filename> のような <acronym>URI</acronym> も可能です。
 296             また、<acronym>URI</acronym> にパラメータを追加した形式、つまり
 297             <filename>controller/action/var1/value1/var2/value2</filename>
 298             のような <acronym>URI</acronym> にもデフォルトで対応しています。
 299         </para>
 300
 301         <para>
 302             ルータのマッチ処理についての例を示します。
 303         </para>
 304
 305         <programlisting language="php"><![CDATA[
 306 // 以下の設定を前提とします
 307 $ctrl->setControllerDirectory(
 308     array(
 309         'default' => '/path/to/default/controllers',
 310         'news'    => '/path/to/news/controllers',
 311         'blog'    => '/path/to/blog/controllers'
 312     )
 313 );
 314
 315 モジュールのみ
 316 http://example/news
 317     module == news
 318
 319 無効なモジュール名は、コントローラ名として扱われます
 320 http://example/foo
 321     controller == foo
 322
 323 モジュール + コントローラ
 324 http://example/blog/archive
 325     module     == blog
 326     controller == archive
 327
 328 モジュール + コントローラ + アクション
 329 http://example/blog/archive/list
 330     module     == blog
 331     controller == archive
 332     action     == list
 333
 334 モジュール + コントローラ + アクション + パラメータ
 335 http://example/blog/archive/list/sort/alpha/date/desc
 336     module     == blog
 337     controller == archive
 338     action     == list
 339     sort       == alpha
 340     date       == desc
 341 ]]></programlisting>
 342
 343         <para>
 344             デフォルトのルートは、<classname>Zend_Controller_Router_Route_Module</classname>
 345             オブジェクトを 'default' という名前 (インデックス) で
 346             RewriteRouter に保存したものです。
 347             これは、以下のようにして作成します。
 348         </para>
 349
 350         <programlisting language="php"><![CDATA[
 351 $compat = new Zend_Controller_Router_Route_Module(array(),
 352                                                   $dispatcher,
 353                                                   $request);
 354 $this->addRoute('default', $compat);
 355 ]]></programlisting>
 356
 357         <para>
 358             このデフォルトルートが不要な場合は、独自の 'デフォルト' ルートで上書きします
 359             (つまり、'default' という名前で保存します)。
 360             あるいは、<methodname>removeDefaultRoutes()</methodname>
 361             で削除することもできます。
 362         </para>
 363
 364         <programlisting language="php"><![CDATA[
 365 // すべてのデフォルトルートを削除します
 366 $router->removeDefaultRoutes();
 367 ]]></programlisting>
 368
 369     </sect2>
 370
 371     <sect2 id="zend.controller.router.rewritebase">
 372         <title>ベース URL およびサブディレクトリ</title>
 373
 374         <para>
 375             Rewrite ルータはサブディレクトリ
 376             (例. <filename>http://domain.com/user/application-root/</filename>)
 377             内でも使用可能です。この場合、アプリケーションのベース <acronym>URL</acronym>
 378             (<filename>/user/application-root</filename>) の自動検出が
 379             <classname>Zend_Controller_Request_Http</classname> によって行われ、適切に使用されます。
 380         </para>
 381
 382         <para>
 383             ベース <acronym>URL</acronym> の検出に失敗する場合は、
 384             <classname>Zend_Controller_Request_Http</classname> のメソッド <methodname>setBaseUrl()</methodname>
 385             を使用してベースパスを上書き指定できます
 386             (<link linkend="zend.controller.request.http.baseurl">ベース URL およびサブディレクトリ</link>を参照ください)。
 387         </para>
 388
 389         <programlisting language="php"><![CDATA[
 390 $request->setBaseUrl('/~user/application-root/');
 391 ]]></programlisting>
 392
 393     </sect2>
 394
 395     <sect2 id="zend.controller.router.global.parameters">
 396         <title>グローバルパラメータ</title>
 397
 398         <para>
 399             グローバルパラメータをルータ内で設定できます。
 400             これは <methodname>setGlobalParam()</methodname>
 401             によってルートに自動的に適用されます。
 402             グローバルパラメータが設定されているにもかかわらず
 403             直接メソッドによっても設定された場合は、
 404             ユーザが設定したパラメータのほうがグローバルパラメータより優先されます。
 405             グローバルパラメータは、このように設定します。
 406         </para>
 407
 408         <programlisting language="php"><![CDATA[
 409 $router->setGlobalParam('lang', 'en');
 410 ]]></programlisting>
 411     </sect2>
 412
 413     <sect2 id="zend.controller.router.routes">
 414         <title>ルートの型</title>
 415
 416         <xi:include href="Zend_Controller-Router-Route.xml" />
 417         <xi:include href="Zend_Controller-Router-Route-Static.xml" />
 418         <xi:include href="Zend_Controller-Router-Route-Regex.xml" />
 419         <xi:include href="Zend_Controller-Router-Route-Hostname.xml" />
 420         <xi:include href="Zend_Controller-Router-Route-Chain.xml" />
 421         <xi:include href="Zend_Controller-Router-Route-Rest.xml" />
 422     </sect2>
 423
 424     <sect2 id="zend.controller.router.add-config">
 425         <title>RewriteRouter での Zend_Config の使用法</title>
 426
 427         <para>
 428             新しいルートを追加する際に、
 429             いちいちコードを書き換えるのではなく設定ファイルの変更で対応できると便利でしょう。
 430             そんなときには <methodname>addConfig()</methodname> メソッドを使用します。基本的な使用法は、
 431             まず <classname>Zend_Config</classname> 互換の設定を作成し、それをコードに読み込み、
 432             そして RewriteRouter に渡すことです。
 433         </para>
 434
 435         <para>
 436             例として、次のような <acronym>INI</acronym> ファイルを考えてみましょう。
 437         </para>
 438
 439         <programlisting language="php"><![CDATA[
 440 [production]
 441 routes.archive.route = "archive/:year/*"
 442 routes.archive.defaults.controller = archive
 443 routes.archive.defaults.action = show
 444 routes.archive.defaults.year = 2000
 445 routes.archive.reqs.year = "\d+"
 446
 447 routes.news.type = "Zend_Controller_Router_Route_Static"
 448 routes.news.route = "news"
 449 routes.news.defaults.controller = "news"
 450 routes.news.defaults.action = "list"
 451
 452 routes.archive.type = "Zend_Controller_Router_Route_Regex"
 453 routes.archive.route = "archive/(\d+)"
 454 routes.archive.defaults.controller = "archive"
 455 routes.archive.defaults.action = "show"
 456 routes.archive.map.1 = "year"
 457 ; あるいは: routes.archive.map.year = 1
 458 ]]></programlisting>
 459
 460         <para>
 461             上の <acronym>INI</acronym> ファイルを、次のようにして
 462             <classname>Zend_Config</classname> オブジェクトに読み込みます。
 463         </para>
 464
 465         <programlisting language="php"><![CDATA[
 466 $config = new Zend_Config_Ini('/path/to/config.ini', 'production');
 467 $router = new Zend_Controller_Router_Rewrite();
 468 $router->addConfig($config, 'routes');
 469 ]]></programlisting>
 470
 471         <para>
 472             上の例では、<acronym>INI</acronym> ファイルの 'routes' セクションを使用してルートを決めるよう、
 473             ルータに指定しています。このセクションの第一レベルのキーがルート名に対応します。
 474             上の例だと 'archive' と 'news' がこれにあたります。
 475             ルートの各エントリには、最低限 'route' エントリとひとつ以上の 'defaults'
 476             エントリが必要となります。また、オプションでひとつ以上の 'reqs'
 477             ('required' の略) も指定できます。ここで指定したものが、それぞれ
 478             <classname>Zend_Controller_Router_Route_Interface</classname>
 479             オブジェクトに対する引数となります。オプションのキー 'type' を使用すると、
 480             特定のルートで使用するルートクラスの型を指定できます。デフォルトでは、これは
 481             <classname>Zend_Controller_Router_Route</classname> となります。上の例では、
 482             'news' ルートで
 483             <classname>Zend_Controller_Router_Route_Static</classname>
 484             を使用するようにしています。
 485         </para>
 486     </sect2>
 487
 488     <sect2 id="zend.controller.router.subclassing">
 489         <title>ルータのサブクラスの作成</title>
 490
 491         <para>
 492             標準の rewrite ルータには、必要となるであろう機能のほとんどが組み込まれています。
 493             もし新しいルータ型を作成する必要があるとすれば、
 494             それは既存のルートに対して新しい機能を追加したり機能を変更したりしたい場合くらいでしょう。
 495         </para>
 496
 497         <para>
 498             どこかで、既存のものとはまったく異なるルーティング処理が必要となったとしましょう。
 499             そんな場合には <classname>Zend_Controller_Router_Interface</classname>
 500             を使用します。これは、ルータとして最低限必要なひとつのメソッドのみを定義したインターフェイスです。
 501         </para>
 502
 503         <programlisting language="php"><![CDATA[
 504 interface Zend_Controller_Router_Interface
 505 {
 506   /**
 507    * @param  Zend_Controller_Request_Abstract $request
 508    * @throws Zend_Controller_Router_Exception
 509    * @return Zend_Controller_Request_Abstract
 510    */
 511   public function route(Zend_Controller_Request_Abstract $request);
 512 }
 513 ]]></programlisting>
 514
 515         <para>
 516             ルーティング処理は、システムが最初にリクエストを受け取った際に一度だけ行われます。
 517             ルータの役割は、リクエストの内容に応じてコントローラやアクションとオプションパラメータを決定し、
 518             それをリクエストに設定することです。
 519             その後、リクエストオブジェクトがディスパッチャに渡されます。
 520             ルートに対応するディスパッチトークンがない場合は、ルータは何も行いません。
 521         </para>
 522     </sect2>
 523 </sect1>
 524 <!--
 525 vim:se ts=4 sw=4 et:
 526 -->