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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <!-- EN-Revision: 21661 -->
   4 <sect3 id="zend.controller.router.routes.standard">
   5     <title>Zend_Controller_Router_Route</title>
   6
   7     <para>
   8         <classname>Zend_Controller_Router_Route</classname> はフレームワークの標準のルートです。
   9         簡単に利用でき、柔軟なルート定義が可能です。各ルートには、まず
  10         (静的および動的な) <acronym>URL</acronym> のマッピングが含まれ、
  11         そしてデフォルト値および変数についての制限を指定して初期化します。
  12     </para>
  13
  14     <para>
  15         とある架空のアプリケーションで、コンテンツの作者情報のページが必要になったとしましょう。
  16         ブラウザで <filename>http://domain.com/author/martel</filename>
  17         にアクセスした際に、"martel" とかいう人についての情報を見たいわけです。
  18         この機能を実現するためのルートは、次のようになります。
  19     </para>
  20
  21     <programlisting language="php"><![CDATA[
  22 $route = new Zend_Controller_Router_Route(
  23     'author/:username',
  24     array(
  25         'controller' => 'profile',
  26         'action'     => 'userinfo'
  27     )
  28 );
  29
  30 $router->addRoute('user', $route);
  31 ]]></programlisting>
  32
  33     <para>
  34         <classname>Zend_Controller_Router_Route</classname>
  35         のコンストラクタの最初のパラメータは、ルートの定義です。
  36         これを <acronym>URL</acronym> にマッチさせます。ルート定義は静的な部分と動的な部分で構成され、
  37         それをスラッシュ ('/') で連結します。
  38         静的な部分は単なるテキスト (例. <command>author</command>) です。
  39         動的な部分を変数と呼び、変数名の前にコロンをつけて
  40         (例. <command>:username</command>) 表します。
  41     </para>
  42
  43     <note>
  44         <title>文字の使用法</title>
  45
  46         <para>
  47             現在の実装では、(スラッシュ以外の)
  48             任意の文字を変数名として使用できます。しかし、
  49             <acronym>PHP</acronym> の変数名として使用できる文字だけを用いることを強く推奨します。
  50             このようにしておくことで、
  51             将来実装が変更されたときにバグを引き起こす可能性を抑えられます。
  52         </para>
  53     </note>
  54
  55     <para>
  56         この例のルートは、ブラウザで
  57         <filename>'http://domain.com/author/martel'</filename> を指した際にマッチします。
  58         この場合、すべての変数の値が <classname>Zend_Controller_Request</classname>
  59         オブジェクトに注入され、<classname>ProfileController</classname> からアクセスできるようになります。
  60         この例が返す変数は、以下のようなキーと値のペアを持つ配列となります。
  61     </para>
  62
  63     <programlisting language="php"><![CDATA[
  64 $values = array(
  65     'username'   => 'martel',
  66     'controller' => 'profile',
  67     'action'     => 'userinfo'
  68 );
  69 ]]></programlisting>
  70
  71     <para>
  72         その後、<classname>Zend_Controller_Dispatcher</classname> は
  73         (デフォルトモジュールの) <classname>ProfileController</classname> クラスにある
  74         <methodname>userinfoAction()</methodname> メソッドを実行します。変数にアクセスするには、
  75         <methodname>Zend_Controller_Action::_getParam()</methodname> あるいは
  76         <methodname>Zend_Controller_Request::getParam()</methodname> メソッドを使用します。
  77     </para>
  78
  79     <programlisting language="php"><![CDATA[
  80 public function userinfoAction()
  81 {
  82     $request = $this->getRequest();
  83     $username = $request->getParam('username');
  84
  85     $username = $this->_getParam('username');
  86 }
  87 ]]></programlisting>
  88
  89     <para>
  90         ルート定義には、特殊文字 (ワイルドカード)
  91         を含めることができます。これは '*' 記号で表します。
  92         これを使用して、Module ルートと同様にパラメータを扱う
  93         (変数名 => 値 のペアを <acronym>URI</acronym> で定義する) ことができます。
  94         次のルートは、Module ルートの挙動をまねたものです。
  95     </para>
  96
  97     <programlisting language="php"><![CDATA[
  98 $route = new Zend_Controller_Router_Route(
  99     ':module/:controller/:action/*',
 100     array('module' => 'default')
 101 );
 102 $router->addRoute('default', $route);
 103 ]]></programlisting>
 104
 105     <sect4 id="zend.controller.router.routes.standard.variable-defaults">
 106         <title>変数のデフォルト</title>
 107
 108         <para>
 109             ルートで使用するすべての変数についてデフォルト値を指定できます。
 110             これは、 <classname>Zend_Controller_Router_Route</classname>
 111             のコンストラクタの 2 番目のパラメータで指定します。
 112             このパラメータは、変数名をキーとする配列で、
 113             対応する値にそのデフォルト値を指定します。
 114         </para>
 115
 116         <programlisting language="php"><![CDATA[
 117 $route = new Zend_Controller_Router_Route(
 118     'archive/:year',
 119     array('year' => 2006)
 120 );
 121 $router->addRoute('archive', $route);
 122 ]]></programlisting>
 123
 124         <para>
 125             上のルートは <filename>'http://domain.com/archive/2005'</filename> および
 126             <filename>'http://example.com/archive'</filename>
 127             のような <acronym>URL</acronym> にマッチします。後者の場合、変数 year にはデフォルト値である
 128             2006 が設定されます。
 129         </para>
 130
 131         <para>
 132             この例は、year 変数をリクエストオブジェクトに注入することになります。
 133             そしてルーティング情報が存在しない
 134             (コントローラやアクションのパラメータが定義されていない) ので、
 135             アプリケーションはデフォルトのコントローラのデフォルトアクションメソッド
 136             (ともに <classname>Zend_Controller_Dispatcher_Abstract</classname> で定義されています)
 137             にディスパッチします。より使いやすくするには、
 138             ルートのデフォルトとしてコントローラとアクションを定義しておく必要があります。
 139         </para>
 140
 141         <programlisting language="php"><![CDATA[
 142 $route = new Zend_Controller_Router_Route(
 143     'archive/:year',
 144     array(
 145         'year'       => 2006,
 146         'controller' => 'archive',
 147         'action'     => 'show'
 148     )
 149 );
 150 $router->addRoute('archive', $route);
 151 ]]></programlisting>
 152
 153         <para>
 154             このルートは、<classname>ArchiveController</classname> の
 155             <methodname>showAction()</methodname> を実行します。
 156         </para>
 157
 158     </sect4>
 159
 160     <sect4 id="zend.controller.router.routes.standard.variable-requirements">
 161         <title>変数の制約</title>
 162
 163         <para>
 164             <classname>Zend_Controller_Router_Route</classname> のコンストラクタの
 165             三番目のパラメータで、変数の制約を指定できます。
 166             これは、正規表現で指定します。
 167         </para>
 168
 169         <programlisting language="php"><![CDATA[
 170 $route = new Zend_Controller_Router_Route(
 171     'archive/:year',
 172     array(
 173         'year'       => 2006,
 174         'controller' => 'archive',
 175         'action'     => 'show'
 176     ),
 177     array('year' => '\d+')
 178 );
 179 $router->addRoute('archive', $route);
 180 ]]></programlisting>
 181
 182         <para>
 183             上の例のルートでは、year 変数の値が数値データである場合にのみ
 184             Rewrite ルータにマッチします。つまり
 185             <filename>http://domain.com/archive/2345</filename> はマッチしますが
 186             <filename>http://example.com/archive/test</filename> はマッチしません。
 187             この場合はチェイン内の次のルートに処理を移します。
 188         </para>
 189     </sect4>
 190
 191     <sect4 id="zend.controller.router.routes.standard.translated-segments">
 192         <title>翻訳済みセグメント</title>
 193
 194         <para>
 195             標準のルートは、翻訳済みセグメントをサポートします。この機能を使用するには、
 196             次のいずれかの方法で翻訳器 (<classname>Zend_Translate</classname> のインスタンス)
 197             を定義しなければなりません。
 198         </para>
 199
 200         <itemizedlist>
 201             <listitem>
 202                 <para>
 203                     レジストリに、キー <classname>Zend_Translate</classname> で格納する
 204                 </para>
 205             </listitem>
 206
 207             <listitem>
 208                 <para>
 209                     静的メソッド
 210                     <methodname>Zend_Controller_Router_Route::setDefaultTranslator()</methodname> で設定する
 211                 </para>
 212             </listitem>
 213
 214             <listitem>
 215                 <para>
 216                     コンストラクタの 4 番目のパラメータとして渡す
 217                 </para>
 218             </listitem>
 219         </itemizedlist>
 220
 221         <para>
 222             デフォルトでは、<classname>Zend_Translate</classname>
 223             のインスタンスで指定したロケールを使用します。これを上書きするには、
 224             (<classname>Zend_Locale</classname> のインスタンスあるいはロケール文字列で)
 225             次のいずれかの方法で設定します。
 226         </para>
 227
 228         <itemizedlist>
 229             <listitem>
 230                 <para>
 231                     レジストリに、キー <classname>Zend_Locale</classname> で格納する
 232                 </para>
 233             </listitem>
 234
 235             <listitem>
 236                 <para>
 237                     静的メソッド
 238                     <methodname>Zend_Controller_Router_Route::setDefaultLocale()</methodname> で設定する
 239                 </para>
 240             </listitem>
 241
 242             <listitem>
 243                 <para>
 244                     コンストラクタの 5 番目のパラメータとして渡す
 245                 </para>
 246             </listitem>
 247
 248             <listitem>
 249                 <para>
 250                     アセンブルメソッドのパラメータ <command>@locale</command> として渡す
 251                 </para>
 252             </listitem>
 253         </itemizedlist>
 254
 255         <para>
 256             翻訳済みセグメントはふたつの部分に分かれます。
 257             固定セグメントの前には <emphasis>@</emphasis> 記号がひとつつき、
 258             アセンブル時に現在のロケールに翻訳され、
 259             マッチングの際にはメッセージ ID に戻されます。
 260             動的セグメントの前には <command>:@</command> がつきます。
 261             アセンブルの際に、指定したパラメータが翻訳され、
 262             パラメータの位置に挿入されます。
 263             マッチングの際には、<acronym>URL</acronym> の翻訳済みパラメータが
 264             メッセージ ID に戻されます。
 265         </para>
 266
 267         <note>
 268             <title>メッセージ ID と分割された言語ファイル</title>
 269
 270             <para>
 271                 ルートの中で使いたいメッセージ ID が、
 272                 ビュースクリプトやその他の部分ですでに使われていることもあるでしょう。
 273                 <acronym>URL</acronym> の安全性を確保するには、
 274                 ルートで使用するメッセージを別の言語ファイルに分割しなければなりません。
 275             </para>
 276         </note>
 277
 278         <para>
 279             標準のルートで翻訳済みセグメントを使用するための準備として
 280             もっともシンプルな方法は、次のようになります。
 281         </para>
 282
 283         <programlisting language="php"><![CDATA[
 284 // 翻訳器を準備します
 285 $translator = new Zend_Translate(
 286     array(
 287         'adapter' => 'array',
 288         'content' => array(),
 289         'locale'  => 'en'
 290     )
 291 );
 292 $translator->addTranslation(
 293     array(
 294         'content' =>
 295             array(
 296                 'archive' => 'archiv',
 297                 'year'    => 'jahr',
 298                 'month'   => 'monat',
 299                 'index'   => 'uebersicht'
 300             ),
 301         'locale'  => 'de'
 302     )
 303 );
 304
 305 // 現在のロケールを翻訳器に設定します
 306 $translator->setLocale('en');
 307
 308 // ルートのデフォルト翻訳器として設定します
 309 Zend_Controller_Router_Route::setDefaultTranslator($translator);
 310 ]]></programlisting>
 311
 312         <para>
 313             これは、静的セグメントを使用する例です。
 314         </para>
 315
 316         <programlisting language="php"><![CDATA[
 317 // ルートを作成します
 318 $route = new Zend_Controller_Router_Route(
 319     '@archive',
 320     array(
 321         'controller' => 'archive',
 322         'action'     => 'index'
 323     )
 324 );
 325 $router->addRoute('archive', $route);
 326
 327 // URL をデフォルトのロケールでアセンブルします: archive
 328 $route->assemble(array());
 329
 330 // URL をドイツ語でアセンブルします: archiv
 331 $route->assemble(array());
 332 ]]></programlisting>
 333
 334         <para>
 335             動的セグメントを使用すると、
 336             モジュールルートの翻訳済みバージョンを作ることができます。
 337         </para>
 338
 339         <programlisting language="php"><![CDATA[
 340 // ルートを作成します
 341 $route = new Zend_Controller_Router_Route(
 342     ':@controller/:@action/*',
 343     array(
 344         'controller' => 'index',
 345         'action'     => 'index'
 346     )
 347 );
 348 $router->addRoute('archive', $route);
 349
 350 // URL をデフォルトのロケールでアセンブルします: archive/index/foo/bar
 351 $route->assemble(array('controller' => 'archive', 'foo' => 'bar'));
 352
 353 // URL をドイツ語でアセンブルします: archiv/uebersicht/foo/bar
 354 $route->assemble(array('controller' => 'archive', 'foo' => 'bar'));
 355 ]]></programlisting>
 356
 357         <para>
 358             静的セグメントと動的セグメントを同時に使用することもできます。
 359         </para>
 360
 361         <programlisting language="php"><![CDATA[
 362 // ルートを作成します
 363 $route = new Zend_Controller_Router_Route(
 364     '@archive/:@mode/:value',
 365     array(
 366         'mode'       => 'year'
 367         'value'      => 2005,
 368         'controller' => 'archive',
 369         'action'     => 'show'
 370     ),
 371     array('mode'  => '(month|year)'
 372           'value' => '\d+')
 373 );
 374 $router->addRoute('archive', $route);
 375
 376 // URL をデフォルトのロケールでアセンブルします: archive/month/5
 377 $route->assemble(array('mode' => 'month', 'value' => '5'));
 378
 379 // URL をドイツ語でアセンブルします: archiv/monat/5
 380 $route->assemble(array('mode' => 'month', 'value' => '5', '@locale' => 'de'));
 381 ]]></programlisting>
 382     </sect4>
 383 </sect3>
 384 <!--
 385 vim:se ts=4 sw=4 et:
 386 -->