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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <!-- EN-Revision: 17592 -->
   4 <sect3 id="zend.controller.router.routes.regex">
   5     <title>Zend_Controller_Router_Route_Regex</title>
   6
   7     <para>
   8         デフォルトのルートや静的なルートに加えて、正規表現によるルートも使用可能です。
   9         このルートは他のものに比べてより強力で柔軟なものですが、
  10         多少複雑になってしまいます。そして、より高速になります。
  11     </para>
  12
  13     <para>
  14         標準のルートと同様、このルートを初期化する際にはルートの定義とデフォルトを指定する必要があります。
  15         サンプルとして、archive ルートを作成してみましょう。
  16         これは先ほど定義したものとほぼ同じですが、今回は Regex ルートを使用しています。
  17     </para>
  18
  19     <programlisting language="php"><![CDATA[
  20 $route = new Zend_Controller_Router_Route_Regex(
  21     'archive/(\d+)',
  22     array(
  23         'controller' => 'archive',
  24         'action'     => 'show'
  25     )
  26 );
  27 $router->addRoute('archive', $route);
  28 ]]></programlisting>
  29
  30     <para>
  31         定義された正規表現のパターンが、リクエストオブジェクトに注入されます。
  32         上の例では、<filename>http://domain.com/archive/2006</filename>
  33         がマッチした後の結果の値は次のような配列になります。
  34     </para>
  35
  36     <programlisting language="php"><![CDATA[
  37 $values = array(
  38     1            => '2006',
  39     'controller' => 'archive',
  40     'action'     => 'show'
  41 );
  42 ]]></programlisting>
  43
  44     <note>
  45         <para>
  46             ルータとのマッチングを行う前に、<acronym>URL</acronym> の先頭と最後のスラッシュは取り除かれます。
  47             結果として、<acronym>URL</acronym> <filename>http://domain.com/foo/bar/</filename>
  48             は正規表現 <filename>foo/bar</filename> にマッチすることになります。
  49             <filename>/foo/bar</filename> にはマッチしません。
  50         </para>
  51     </note>
  52
  53     <note>
  54         <para>
  55             行頭と行末を表す文字 (それぞれ '^' および '$')
  56             が、すべての式の前後に自動的に付加されます。
  57             したがって、これらは正規表現で指定する必要はありません。
  58         </para>
  59     </note>
  60
  61     <note>
  62         <para>
  63             このルートクラスは、区切り文字として '<emphasis>#</emphasis>' を使用します。
  64             つまり、ルート定義の中にハッシュ文字 ('#')
  65             がある場合は、それをエスケープする必要があるということです。
  66             スラッシュ ('/') をエスケープする必要はありません。
  67             '#' (アンカー) は通常はウェブサーバに渡されることはないので、
  68             エスケープが必要になることはまずないでしょう。
  69         </para>
  70     </note>
  71
  72     <para>
  73         定義されたサブパターンの内容は、通常通りの方法で取得できます。
  74     </para>
  75
  76     <programlisting language="php"><![CDATA[
  77 public function showAction()
  78 {
  79     $request = $this->getRequest();
  80     $year    = $request->getParam(1); // $year = '2006';
  81 }
  82 ]]></programlisting>
  83
  84     <note>
  85         <para>このキーは、文字列 ('1') ではなく数値の 1 であることに注意しましょう。</para>
  86     </note>
  87
  88     <para>
  89         このルートは、標準のルートとまったく同様に動作するわけではありません。
  90         'year' のデフォルトが設定されていないからです。
  91         また、year のデフォルトを設定してこれをオプション扱いにしたとしても、
  92         最後のスラッシュをどうするかという問題が残ります。
  93         これを解決するには、year 部をスラッシュを含めてオプションにし、
  94         その数値部のみを取得するようにします。
  95     </para>
  96
  97     <programlisting language="php"><![CDATA[
  98 $route = new Zend_Controller_Router_Route_Regex(
  99     'archive(?:/(\d+))?',
 100     array(
 101         1            => '2006',
 102         'controller' => 'archive',
 103         'action'     => 'show'
 104     )
 105 );
 106 $router->addRoute('archive', $route);
 107 ]]></programlisting>
 108
 109     <para>
 110         まだ問題が残っていることにおそらくお気づきでしょう。
 111         パラメータとして数値のキーを使用するのはなかなか難しく、
 112         長い目で見れば問題を引き起こす可能性が高くなります。
 113         そこで三番目のパラメータの登場です。
 114         このパラメータは、正規表現サブパターンとパラメータ名のキーを関連付けます。
 115         簡単な例を見てみましょう。
 116     </para>
 117
 118     <programlisting language="php"><![CDATA[
 119 $route = new Zend_Controller_Router_Route_Regex(
 120     'archive/(\d+)',
 121     array(
 122         'controller' => 'archive',
 123         'action' => 'show'
 124     ),
 125     array(
 126         1 => 'year'
 127     )
 128 );
 129 $router->addRoute('archive', $route);
 130 ]]></programlisting>
 131
 132     <para>
 133         この結果は次のようになり、これがリクエストオブジェクトに格納されます。
 134     </para>
 135
 136     <programlisting language="php"><![CDATA[
 137 $values = array(
 138     'year'       => '2006',
 139     'controller' => 'archive',
 140     'action'     => 'show'
 141 );
 142 ]]></programlisting>
 143
 144     <para>
 145         関連付けは両方の方法で定義でき、任意の環境 (例. Zend_Config) で動作します。
 146         キーには変数名あるいはサブパターン番号のいずれかを含めることができます。
 147     </para>
 148
 149     <programlisting language="php"><![CDATA[
 150 $route = new Zend_Controller_Router_Route_Regex(
 151     'archive/(\d+)',
 152     array( ... ),
 153     array(1 => 'year')
 154 );
 155
 156 // あるいは
 157
 158 $route = new Zend_Controller_Router_Route_Regex(
 159     'archive/(\d+)',
 160     array( ... ),
 161     array('year' => 1)
 162 );
 163 ]]></programlisting>
 164
 165     <note>
 166         <para>
 167             サブパターンのキーは整数値でなければなりません。
 168         </para>
 169     </note>
 170
 171     <para>
 172         リクエストの値から数値キーが消え、代わりに名前がつけられたことに注目しましょう。
 173         もちろん、お望みなら数値での指定と名前での指定を共用することもできます。
 174     </para>
 175
 176     <programlisting language="php"><![CDATA[
 177 $route = new Zend_Controller_Router_Route_Regex(
 178     'archive/(\d+)/page/(\d+)',
 179     array( ... ),
 180     array('year' => 1)
 181 );
 182 ]]></programlisting>
 183
 184     <para>
 185         この結果、リクエスト内には数値キーと名前つきキーが共存することになります。
 186         たとえば、<acronym>URL</acronym> <filename>http://domain.com/archive/2006/page/10</filename>
 187         は次のような値になります。
 188     </para>
 189
 190     <programlisting language="php"><![CDATA[
 191 $values = array(
 192     'year'       => '2006',
 193     2            => 10,
 194     'controller' => 'archive',
 195     'action'     => 'show'
 196 );
 197 ]]></programlisting>
 198
 199     <para>
 200         正規表現を簡単に反転させることはできないので、
 201         <acronym>URL</acronym> ヘルパーやこのクラスのメソッドを使用するには
 202         逆の <acronym>URL</acronym> を準備しておく必要があります。
 203         逆方向のパスは <methodname>sprintf()</methodname> 形式の文字列で表し、
 204         コンストラクタの四番目のパラメータとして指定します。
 205     </para>
 206
 207     <programlisting language="php"><![CDATA[
 208 $route = new Zend_Controller_Router_Route_Regex(
 209     'archive/(\d+)',
 210     array( ... ),
 211     array('year' => 1),
 212     'archive/%s'
 213 );
 214 ]]></programlisting>
 215
 216     <para>
 217         これまで説明してきたことは、すべて標準のルートオブジェクトでも可能なことです。
 218         それでは、Regex ルートを使用するメリットはいったい何なのでしょう?
 219         これを使用すると、あらゆる形式の <acronym>URL</acronym> を制約なしに定義することができます。
 220         仮に、あなたが blog を持っており
 221         <filename>http://domain.com/blog/archive/01-Using_the_Regex_Router.html</filename>
 222         のような <acronym>URL</acronym> を作成したいと考えたとしましょう。
 223         このパスの最後の要素 <filename>01-Using_the_Regex_Router.html</filename>
 224         から記事の ID とタイトル/説明 を取得するにはどうしたらいいでしょうか？
 225         標準のルートでは不可能でしょう。Regex ルートを使用した場合は、
 226         次のようにすることができます。
 227     </para>
 228
 229     <programlisting language="php"><![CDATA[
 230 $route = new Zend_Controller_Router_Route_Regex(
 231     'blog/archive/(\d+)-(.+)\.html',
 232     array(
 233         'controller' => 'blog',
 234         'action'     => 'view'
 235     ),
 236     array(
 237         1 => 'id',
 238         2 => 'description'
 239     ),
 240     'blog/archive/%d-%s.html'
 241 );
 242 $router->addRoute('blogArchive', $route);
 243 ]]></programlisting>
 244
 245     <para>
 246         regex ルートは標準のルートよりはるかに柔軟性があるということが、
 247         ここからもわかります。
 248     </para>
 249 </sect3>
 250 <!--
 251 vim:se ts=4 sw=4 et:
 252 -->