runtime-routing.md 38.7 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
ルーティングと URL 生成
=======================

Yii のアプリケーションがリクエストされた URL の処理を開始するときに、最初に実行するステップは URL を解析して
[ルート](structure-controllers.md#routes) にすることです。次に、リクエストを処理するために、このルートを使って、
対応する [コントローラアクション](structure-controllers.md) のインスタンスが作成されます。
このプロセスの全体が *ルーティング* と呼ばれます。

ルーティングの逆のプロセスが *URL 生成* と呼ばれます。これは、与えられたルートとそれに結び付いたクエリパラメータから
URL を生成するものです。生成された URL が後でリクエストされたとき、ルーティングのプロセスは、その URL を解決して、
元のルートとクエリパラメータに戻すことが出来ます。

ルーティングと URL 生成について責任を持つ主要コンポーネントが [[yii\web\UrlManager|URL マネージャ]] であり、`urlManager`
アプリケーションコンポーネントとして登録されているものです。[[yii\web\UrlManager|URL マネージャ]] は、入ってくるリクエストを
ルートとそれに結び付いたクエリパラメータとして解析するための [[yii\web\UrlManager::parseRequest()|parseRequest()]] メソッドと、
与えられたルートとそれに結び付いたクエリパラメータから URL を生成するための [[yii\web\UrlManager::createUrl()|createUrl()]]
メソッドを提供するものです。

アプリケーションコンフィギュレーションの `urlManager` コンポーネントを構成することによって、既存のアプリケーションコードを
修正することなく、任意の URL 形式をアプリケーションに認識させることが出来ます。例えば、`post/view` アクションのための URL
を生成するために、次のコードを使うことが出来ます:
22 23 24 25

```php
use yii\helpers\Url;

26
// Url::to() は UrlManager::createUrl() を呼び出して URL を生成します
27 28 29
$url = Url::to(['post/view', 'id' => 100]);
```

30 31
このコードによって生成される URL は、`urlManager` のコンフィギュレーションに応じて、下記の形式のうちの一つ (またはその他の形式)
になります。そしてまた、生成された URL が後でリクエストされたときには、解析されて元のルートとクエリパラメータに戻されます。
32 33 34 35 36 37 38 39

```
/index.php?r=post/view&id=100
/index.php/post/100
/posts/100
```


40 41 42
## URL 形式 <a name="url-formats"></a>

[[yii\web\UrlManager|URL マネージャ]] は二つの URL 形式をサポートします: デフォルトの URL 形式と、綺麗な URL 形式です。
43

44 45 46 47
既定の URL 形式は、`r` というクエリパラメータを使用してルートを表し、通常のクエリパラメータを使用してルートに結び付いたクエリパラメータを表します。
例えば、`/index.php?r=post/view&id=100` という URL は、`post/view` というルートと、`id` というクエリパラメータが 100 であることを表します。
既定の URL 形式は、[[yii\web\UrlManager|URL マネージャ]] についてのコンフィギュレーションを何も必要とせず、
ウェブサーバの設定がどのようなものでも動作します。
48

49 50 51 52 53
綺麗な URL 形式は、エントリスクリプトの名前に続く追加のパスを使用してルートとそれに結び付いたクエリパラメータを表します。
例えば、`/index.php/post/100` という URL の追加のパスは `/post/100` ですが、適切な [[yii\web\UrlManager::rules|URL 規則]]
があれば、この URL が `post/view` というルートと `id` というクエリパラメータが 100 であることを表すことが出来ます。
綺麗な URL 形式を使用するためには、URL をどのように表現すべきかという実際の要求に従って、一連の [[yii\web\UrlManager::rules|URL 規則]]
を設計する必要があります。
54

55 56
この二つの URL 形式は、[[yii\web\UrlManager|URL マネージャ]] の [[yii\web\UrlManager::enablePrettyUrl|enablePrettyUrl]]
プロパティを ON/OFF することによって、他のアプリケーションコードを少しも変えることなく、切り替えることが出来ます。
57 58


59
## ルーティング <a name="routing"></a>
60

61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97
ルーティングは二つのステップを含みます。最初のステップでは、入ってくるリクエストが解析されて、ルートとそれに結び付いたクエリパラメータに分解されます。そして、第二のステップでは、解析されたルートに対応する [コントローラアクション](structure-controllers.md)
がリクエストを処理するために生成されます。

既定の URL 形式を使っている場合は、リクエストからルートを解析することは、`r` という名前の `GET` クエリパラメータを取得するだけの
簡単なことです。

綺麗な URL 形式を使っている場合は、[[yii\web\UrlManager|URL マネージャ]] が登録されている [[yii\web\UrlManager::rules|URL 規則]]
を調べます。合致する規則が見つかれば、リクエストをルートに解決することが出来ます。そういう規則が見つからなかったら、
[[yii\web\NotFoundHttpException]] 例外が投げられます。

いったんリクエストからルートが解析されたら、今度はルートによって特定されるコントローラアクションを生成する番です。
ルートはその中にあるスラッシュによって複数の部分に分けられます。例えば、`site/index``site``index` に分割されます。
その各部分がモジュール、コントローラ、アクションを参照する ID となります。アプリケーションは、ルートの中の最初の部分から始めて、
下記のステップを踏んで、モジュール (もし有れば)、コントローラ、アクションを生成します。

1. アプリケーションをカレントモジュールとして設定します。
2. カレントモジュールの [[yii\base\Module::controllerMap|コントローラマップ]] がカレント ID を含むかどうかを調べます。
   もしそうであれば、マップの中で見つかったコントローラコンフィギュレーションに従ってコントローラオブジェクトが生成され、
   ルートの残りの部分を処理するために、ステップ 5 に飛びます。
3. ID がカレントモジュールの [[yii\base\Module::modules|modules]] プロパティのリストに挙げられたモジュールを指すかどうかを調べます。
   もしそうであれば、モジュールのリストで見つかったコンフィギュレーションに従ってモジュールが生成されます。そして、ステップ 2
   に戻って、新しく生成されたモジュールのコンテキストのもとで、ルートの次の部分を処理します。
4. ID をコントローラ ID として扱ってコントローラオブジェクトを生成します。そしてルートの残りの部分を持って次のステップに進みます。
5. コントローラは、[[yii\base\Controller::actions()|アクションマップ]] の中にカレント ID があるかどうかを調べます。もし有れば、
   マップの中で見つかったコンフィギュレーションに従ってアクションを生成します。もし無ければ、カレント ID
   に対応するアクションメソッドによって定義されるインラインアクションを生成しようと試みます。

上記のステップの中で、何かエラーが発生すると、[[yii\web\NotFoundHttpException]] が投げられて、
ルーティングのプロセスが失敗したことが示されます。


### デフォルトルート <a name="default-route"></a>

リクエストから解析されたルートが空っぽになった場合は、いわゆる *デフォルトルート* が代りに使用されることになります。既定では、
デフォルトルートは `site/index` であり、`site` コントローラの `index` アクションを指します。デフォルトルートは、次のように、
アプリケーションコンフィギュレーションの中でアプリケーションの [[yii\web\Application::defaultRoute|defaultRoute]]
プロパティを構成することによって、カスタマイズすることが出来ます。
98 99 100 101 102 103 104 105 106

```php
[
    // ...
    'defaultRoute' => 'main/index',
];
```


107
### `catchAll` ルート <a name="catchall-route"></a>
108

109 110 111
たまには、ウェブアプリケーションを一時的にメンテナンスモードにして、全てのリクエストに対して同じ「お知らせ」のページを表示したいことがあるでしょう。
この目的を達する方法はたくさんありますが、最も簡単な方法の一つは、次のように、
アプリケーションのコンフィギュレーションの中で [[yii\web\Application::catchAll]] プロパティを構成することです。
112 113 114 115 116 117 118 119

```php
[
    // ...
    'catchAll' => ['site/offline'],
];
```

120 121
上記のコンフィギュレーションによって、入ってくる全てのリクエストを処理するために
`site/offline` アクションが使われるようになります。
122

123 124
`catchAll` プロパティは配列を取り、最初の要素はルートを指定し、残りの要素 (「名前-値」のペア) は
[アクションのパラメータ](structure-controllers.md#action-parameters) を指定するものでなければなりません。
125 126


127
## URL を生成する <a name="creating-urls"></a>
128

129 130
Yii は、与えられたルートとそれに結び付けられるクエリパラメータからさまざまな URL を生成する
[[yii\helpers\Url::to()]] というヘルパーメソッドを提供しています。例えば、
131 132 133 134

```php
use yii\helpers\Url;

135
// ルートへの URL を生成する: /index.php?r=post/index
136 137
echo Url::to(['post/index']);

138
// パラメータを持つルートへの URL を生成する: /index.php?r=post/view&id=100
139 140
echo Url::to(['post/view', 'id' => 100]);

141
// アンカー付きの URL を生成する: /index.php?r=post/view&id=100#content
142 143
echo Url::to(['post/view', 'id' => 100, '#' => 'content']);

144
// 絶対 URL を生成する: http://www.example.com/index.php?r=post/index
145 146
echo Url::to(['post/index'], true);

147
// https スキームを使って絶対 URL を生成する: https://www.example.com/index.php?r=post/index
148 149 150
echo Url::to(['post/index'], 'https');
```

151 152 153
上記の例では、既定の URL 形式が使われていると仮定していることに注意してください。綺麗な URL
形式が有効になっている場合は、生成される URL は、使われている [[yii\web\UrlManager::rules|URL 規則]]
に従って、違うものになります。
154

155 156
[[yii\helpers\Url::to()]] メソッドに渡されるルートの意味は、コンテキストに依存します。ルートは
*相対* ルートか *絶対* ルートかのどちらかであり、下記の規則によって正規化されます。
157

158 159 160 161 162
- ルートが空文字列である場合は、現在リクエストされている [[yii\web\Controller::route|ルート]] が使用されます。
- ルートがスラッシュを全く含まない場合は、カレントコントローラのアクション ID であると見なされて、
  カレントコントローラの [[\yii\web\Controller::uniqueId|uniqueId]] の値が前置されます。
- ルートが先頭にスラッシュを含まない場合は、カレントモジュールに対する相対ルートと見なされて、
  カレントモジュールの [[\yii\base\Module::uniqueId|uniqueId]] の値が前置されます。
163

164
例えば、カレントモジュールが `admin` であり、カレントコントローラが `post` であると仮定すると、
165 166 167 168

```php
use yii\helpers\Url;

169
// 現在リクエストされているルート: /index.php?r=admin/post/index
170 171
echo Url::to(['']);

172
// アクション ID だけの相対ルート: /index.php?r=admin/post/index
173 174
echo Url::to(['index']);

175
// 相対ルート: /index.php?r=admin/post/index
176 177
echo Url::to(['post/index']);

178
// 絶対ルート: /index.php?r=post/index
179 180 181
echo Url::to(['/post/index']);
```

182 183 184 185 186
[[yii\helpers\Url::to()]] メソッドは、[[yii\web\UrlManager|URL マネージャ]] の
[[yii\web\UrlManager::createUrl()|createUrl()]] メソッド、および、[[yii\web\UrlManager::createAbsoluteUrl()|createAbsoluteUrl()]]
を呼び出すことによって実装されています。
次に続くいくつかの項では、[[yii\web\UrlManager|URL マネージャ]] を構成して、生成される URL
の形式をカスタマイズする方法を説明します。
187

188 189
[[yii\helpers\Url::to()]] メソッドは、特定のルートとの関係を持たない URL の生成もサポートしています。
その場合、最初のパラメータとして配列を渡す代りに文字列を渡さなければなりません。例えば、
190 191 192 193
 
```php
use yii\helpers\Url;

194
// 現在リクエストされている URL: /index.php?r=admin/post/index
195 196
echo Url::to();

197
// エイリアス化された URL: http://example.com
198 199 200
Yii::setAlias('@example', 'http://example.com/');
echo Url::to('@example');

201
// 絶対 URL: http://example.com/images/logo.gif
202 203 204
echo Url::to('/images/logo.gif', true);
```

205 206
`to()` メソッドの他にも、[[yii\helpers\Url]]` ヘルパークラスは、便利な URL 生成メソッドをいくつか提供しています。
例えば、
207 208 209 210

```php
use yii\helpers\Url;

211
// ホームページの URL: /index.php?r=site/index
212 213
echo Url::home();

214
// ベース URL。アプリケーションがウェブルートのサブディレクトリに配置されているときに便利
215 216
echo Url::base();

217 218
// 現在リクエストされている URL の canonical URL。
// https://en.wikipedia.org/wiki/Canonical_link_element を参照
219 220
echo Url::canonical();

221
// 現在リクエストされている URL を記憶し、それを後のリクエストの中で呼び戻す。
222 223 224 225 226
Url::remember();
echo Url::previous();
```


227
## 綺麗な URL を使う <a name="using-pretty-urls"></a>
228

229
綺麗な URL を使うためには、アプリケーションコンフィギュレーションの中で `urlManager` コンポーネントを次のように構成します。
230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245

```php
[
    'components' => [
        'urlManager' => [
            'enablePrettyUrl' => true,
            'showScriptName' => false,
            'enableStrictParsing' => true,
            'rules' => [
                // ...
            ],
        ],
    ],
]
```

246 247 248 249 250 251 252 253 254 255 256 257
[[yii\web\UrlManager::enablePrettyUrl|enablePrettyUrl]] プロパティは、綺麗な URL 形式の有効/無効を切り替えますので、必須です。
その他のプロパティはオプションですが、上記で示されているコンフィギュレーションが最もよく用いられているものです。

* [[yii\web\UrlManager::showScriptName|showScriptName]]: このプロパティは、エントリスクリプトを生成される URL に含めるべきかどうかを
  決定します。例えば、このプロパティを true にすると、`/index.php/post/100` という URL を生成する代りに、`/post/100` という URL
  を生成することが出来ます。
* [[yii\web\UrlManager::enableStrictParsing|enableStrictParsing]]: このプロパティは、厳密なリクエスト解析を有効にするかどうかを決定します。
  厳密な解析が有効にされた場合、リクエストされた URL が有効なリクエストとして扱われるためには、それが [[yii\web\UrlManager::rules|rules]]
  の少なくとも一つに合致しなければなりません。そうでなければ、[[yii\web\NotFoundHttpException]] が投げられます。
  厳密な解析が無効にされると、リクエストされた URL が [[yii\web\UrlManager::rules|rules]] のどれにも合致しない場合は、
  URL のパス情報の部分がリクエストされたルートとして扱われます。
* [[yii\web\UrlManager::rules|rules]]: このプロパティが URL を解析および生成するための一連の規則を含みます。
258
  このプロパティが、アプリケーションの固有の要求を満たす形式を持つ URL を生成するために、あなたが主として使うプロパティです。
259

260 261 262 263
> Note|注意: 生成された URL からエントリスクリプト名を隠すためには、[[yii\web\UrlManager::showScriptName|showScriptName]]
  を true に設定するだけでなく、ウェブサーバを構成して、リクエストされた URL が PHP スクリプトを明示的に指定していない場合でも、
  正しい PHP スクリプトを特定出来るようにする必要があります。もしあなたが Apache ウェブサーバを使うつもりなら、
  [インストール](start-installation.md#recommended-apache-configuration) の節で説明されている推奨設定を参照することが出来ます。
264 265


266
### URL 規則 <a name="url-rules"></a>
267

268 269 270 271
URL 規則は [[yii\web\UrlRule]] またはその子クラスのインスタンスです。すべての URL 規則は、URL のパス情報の部分との照合に使われるパターン、
ルート、そして、いくつかのクエリパラメータから構成されます。URL 規則は、パターンがリクエストされた URL と合致する場合に、
リクエストの解析に使用することが出来ます。また、URL 規則は、ルートとクエリパラメータ名が与えられたものと合致する場合に、
URL の生成に使用することが出来ます。
272

273 274 275 276 277 278
綺麗な URL 形式が有効にされている場合、[[yii\web\UrlManager|URL マネージャ]] は、その [[yii\web\UrlManager::rules|rules]]
プロパティに宣言されている URL 規則を使って、入ってくるリクエストを解析と URL の生成を行います。具体的に言えば、
入ってくるリクエストを解析するためには、[[yii\web\UrlManager|URL マネージャ]] は宣言されている順に規則を調べて、リクエストされた
URL に合致する *最初の* 規則を探します。そして、その合致する規則を使って URL を解析して、ルートとそれと結合されたパラメータを得ます。
同じように、URL を生成するためには、[[yii\web\UrlManager|URL マネージャ]] は、与えられたルートとパラメータに合致する最初の規則を探して、
それを使って URL を生成します。
279

280 281 282 283 284
[[yii\web\UrlManager::rules]] は、パターンをキーとし、それに対応するルートを値とする配列として構成することが出来ます。
「パターン - ルート」のペアが、それぞれ、URL 規則を構成します。例えば、次の [[yii\web\UrlManager::rules|rules]]
のコンフィギュレーションは、二つの URL 規則を宣言するものです。最初の規則は `posts` という URL に合致し、それを `post/index`
というルートにマップします。第二の規則は `post/(\d+)` という正規表現にマッチする URL に合致し、それを `post/view`
というルートと `id` という名前のパラメータにマップします。
285 286 287 288 289 290 291 292

```php
[
    'posts' => 'post/index', 
    'post/<id:\d+>' => 'post/view',
]
```

293 294
> Info|情報: 規則のパターンは URL のパス情報の部分との照合に使用されます。例えば、`/index.php/post/100?source=ad`
  のパス情報は `post/100` であり (先頭と末尾のスラッシュは無視します)、これは `post/(\d+)` というパターンに合致します。
295

296 297 298
URL 規則は、「パターン - ルート」のペアとして宣言する以外に、コンフィギュレーション配列として宣言することも出来ます。
すべてのコンフィギュレーション配列が、それぞれ、一つの URL 規則のオブジェクトを構成するために使われます。この形式は、
URL 規則の他のプロパティを構成したい場合に、よく必要になります。例えば、
299 300 301

```php
[
302
    // ... 他の URL 規則 ...
303 304 305 306 307 308 309 310 311
    
    [
        'pattern' => 'posts',
        'route' => 'post/index',
        'suffix' => '.json',
    ],
]
```

312
規則のコンフィギュレーションで `class` を指定しない場合は、既定として、[[yii\web\UrlRule]] が使われます。
313 314


315
### 名前付きパラメータ <a name="named-parameters"></a>
316

317 318 319
URL 規則は、パターンの中で `<ParamName:RgExp>` の形式で指定される、いくつかの名前付きクエリパラメータと結び付けることが出来ます。
ここで、`ParamName` はパラメータ名を指定し、`RegExp` はパラメータの値との照合に使われるオプションの正規表現を指定するものです。
`RegExp` が指定されていない場合は、パラメータの値がスラッシュを含まない文字列であるべきことを意味します。
320

321
> Note|注意: 正規表現はパラメータに対してのみ指定できます。パターンの残りの部分は平文テキストであると見なされます。
322

323 324 325
規則が URL の解析に使われるときには、結び付けられたパラメータに、URL の対応する部分に合致する値が入れられます。
そして、これらのパラメータは、後に `request` アプリケーションコンポーネントによって、`$_GET` に入れられて利用できるようになります。
規則が URL の生成に使われるときは、提供されたパラメータの値を受けて、パラメータが宣言されている所にその値が挿入されます。
326

327
名前付きパラメータの動作を説明するためにいくつかの例を挙げましょう。次の三つの URL 規則を宣言したと仮定してください。
328 329 330 331 332 333 334 335 336

```php
[
    'posts' => 'post/index',
    'post/<id:\d+>' => 'post/view',
    'posts/<year:\d{4}>/<category>' => 'post/index',
]
```

337
規則が URL 解析に使われる場合は:
338

339 340 341 342 343 344 345
- `/index.php/posts` は、最初の規則を使って解析され、ルート `post/index` になります。
- `/index.php/posts/2014/php` は、三番目の規則を使って解析され、ルートは `post/index`、`year` パラメータの値は 2014、
  そして、`category` パラメータの値は `php` となります。
- `/index.php/post/100` は、二番目の規則を使って解析され、ルートが `post/view`、`id` パラメータの値が 100 となります。
- `/index.php/posts/php` は、どのパターンにも合致しないため、[[yii\web\UrlManager::enableStrictParsing]] が true の場合は、
  [[yii\web\NotFoundHttpException]] を引き起こします。[[yii\web\UrlManager::enableStrictParsing]] が false (これが既定値です)
  の場合は、パス情報の部分である `posts/php` がルートとして返されることになります。
346
 
347
規則が URL 生成に使われる場合は:
348

349 350 351 352 353 354 355
- `Url::to(['post/index'])` は、最初の規則を使って、`/index.php/posts` を生成します。
- `Url::to(['post/index', 'year' => 2014, 'category' => 'php'])` は、三番目の規則を使って、`/index.php/posts/2014/php` を生成します。
- `Url::to(['post/view', 'id' => 100])` は、二番目の規則を使って、`/index.php/post/100` を生成します。
- `Url::to(['post/view', 'id' => 100, 'source' => 'ad'])` も、二番目の規則を使って、`/index.php/post/100?source=ad` を生成します。
  `source` パラメータは規則の中で指定されていないので、クエリパラメータとして生成された URL に追加されます。
- `Url::to(['post/index', 'category' => 'php'])` は、どの規則も使わずに、`/index.php/post/index?category=php` を生成します。
  どの規則も当てはまらないため、URL は、単純に、ルートをパス情報とし、すべてのパラメータをクエリ文字列として追加して生成されます。
356 357


358 359
### ルートをパラメータ化する <a name="parameterizing-routes"></a>

360 361
URL 規則のルートにはパラメータ名を埋め込むことが出来ます。このことによって、URL 規則を複数のルートに合致させることが可能になっています。
例えば、以下の規則は `controller` と `action` というパラメータをルートに埋め込んでいます。
362 363 364 365 366 367 368 369 370

```php
[
    '<controller:(post|comment)>/<id:\d+>/<action:(create|update|delete)>' => '<controller>/<action>',
    '<controller:(post|comment)>/<id:\d+>' => '<controller>/view',
    '<controller:(post|comment)>s' => '<controller>/index',
]
```

371 372 373 374 375
`/index.php/comment/100/create` という URL の解析には、最初の規則が適用され、`controller` パラメータには `comment`、
`action` パラメータには `create` がセットされます。こうして、`<controller>/<action>` というルートは、`comment/create`
として解決されます。

同じように、`comment/index` というルートの URL を生成するためには、三番目の規則が適用されて、`index.php/comments` という URL が生成されます。
376

377 378
> Info|情報: ルートをパラメータ化することによって、URL 規則の数を大幅に減らすことが可能になり、
  [[yii\web\UrlManager|URL マネージャ]] のパフォーマンスを目に見えて改善することが出来ます。
379
  
380 381 382 383
既定では、規則の中で宣言されたパラメータは必須となります。リクエストされた URL が特定のパラメータを含まない場合や、
URL が特定のパラメータなしで生成される場合には、規則は適用されません。パラメータのどれかをオプション扱いにしたい場合は、規則の
[[yii\web\UrlRule::defaults|defaults]] プロパティを構成することが出来ます。このプロパティのリストに挙げられたパラメータは
オプション扱いとなり、規定されなかった場合は指定された値を取るようになります。
384

385 386
次の規則の宣言においては、`page` と `tag` のパラメータは両方ともオプション扱いで、規定されなかった場合は、それぞれ、1
と空文字列を取ります。
387 388 389

```php
[
390
    // ... 他の規則 ...
391 392 393 394 395 396 397 398
    [
        'pattern' => 'posts/<page:\d+>/<tag>',
        'route' => 'post/index',
        'defaults' => ['page' => 1, 'tag' => ''],
    ],
]
```

399
上記の規則を以下の URL を解析または生成するために使用することが出来ます。
400

401 402 403 404
* `/index.php/posts`: `page` は 1, `tag` は ''.
* `/index.php/posts/2`: `page` は 2, `tag` は ''.
* `/index.php/posts/2/news`: `page` は 2, `tag` は `'news'`.
* `/index.php/posts/news`: `page` は 1, `tag` は `'news'`.
405

406
オプション扱いのパラメータを使わなければ、同じ結果を得るために 4 個の規則を作らなければならなかったところです。
407 408


409
### サーバ名を持つ規則 <a name="rules-with-server-names"></a>
410

411 412 413
URL 規則のパターンには、ウェブサーバ名を含むことが出来ます。このことが役に立つのは、主として、あなたのアプリケーションが
ウェブサーバ名によって異なる動作をしなければならない場合です。例えば、次の規則は、`http://admin.example.com/login`
という URL を `admin/user/login` のルートとして解析し、`http://www.example.com/login` を `site/login` として解析するものです。
414 415 416 417 418 419 420 421

```php
[
    'http://admin.example.com/login' => 'admin/user/login',
    'http://www.example.com/login' => 'site/login',
]
```

422 423
サーバ名にパラメータを埋め込んで、そこから動的な情報を抽出することも出来ます。例えば、次の規則は `http://en.example.com/posts`
という URL を解析して、`post/index` というルートと `language=en` というパラメータを取得するものです。
424 425 426 427 428 429 430

```php
[
    'http://<language:\w+>.example.com/posts' => 'post/index',
]
```

431 432 433 434
> Note|注意: サーバ名を持つ規則は、エントリスクリプトのサブフォルダをパターンに含むべきではありません。例えば、アプリケーションが
  `http://www.example.com/sandbox/blog` の下にある場合は、`http://www.example.com/sandbox/blog/posts` ではなく、
  `http://www.example.com/posts` というパターンを使うべきです。こうすれば、アプリケーションをどのようなディレクトリに配置しても、
  アプリケーションのコードを変更する必要がなくなります。
435 436


437
### URL 接尾辞 <a name="url-suffixes"></a>
438

439 440 441 442
さまざまな目的から URL に接尾辞を追加したいことがあるでしょう。例えば、静的な HTML ページに見えるように、`.html` を URL
に追加したいかも知れません。また、レスポンスとして期待されているコンテントタイプを示すために、`.json` を URL
に追加したい場合もあるでしょう。アプリケーションのコンフィギュレーションで、次のように、[[yii\web\UrlManager::suffix]]
プロパティを構成することによって、この目的を達することが出来ます。
443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459

```php
[
    'components' => [
        'urlManager' => [
            'enablePrettyUrl' => true,
            'showScriptName' => false,
            'enableStrictParsing' => true,
            'suffix' => '.html',
            'rules' => [
                // ...
            ],
        ],
    ],
]
```

460 461
上記のコンフィギュレーションによって、[[yii\web\UrlManager|URL マネージャ]] は、接尾辞として `.html` の付いた URL
を認識し、また、生成するようになります。
462

463
> Tip|ヒント: URL が全てスラッシュで終るようにするためには、URL 接尾辞として `/` を設定することが出来ます。
464

465 466 467 468 469 470 471
> Note|注意: URL 接尾辞を構成すると、リクエストされた URL が接尾辞を持たない場合は、認識できない URL であると見なされるようになります。
  SEO の目的からも、これが推奨される慣行です。

場合によっては、URL によって異なる接尾辞を使いたいことがあるでしょう。その目的は、個々の URL 規則の [[yii\web\UrlRule::suffix|suffix]]
プロパティを構成することによって達成できます。URL 規則にこのプロパティが設定されている場合は、それが [[yii\web\UrlManager|URL マネージャ]]
レベルの接尾辞の設定をオーバーライドします。例えば、次のコンフィギュレーションには、グローバルな接尾辞 `.html` の代りに
`.json` を使用するカスタマイズされた URL 規則が含まれています。
472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494

```php
[
    'components' => [
        'urlManager' => [
            'enablePrettyUrl' => true,
            'showScriptName' => false,
            'enableStrictParsing' => true,
            'suffix' => '.html',
            'rules' => [
                // ...
                [
                    'pattern' => 'posts',
                    'route' => 'post/index',
                    'suffix' => '.json',
                ],
            ],
        ],
    ],
]
```


495
### HTTP メソッド <a name="http-methods"></a>
496

497 498 499 500 501 502
RESTful API を実装するときは、使用されている HTTP メソッドに応じて、同一の URL を異なるルートとして解析することが
必要になル場合がよくあります。これは、規則のパターンにサポートされている HTTP メソッドを前置することによって、
簡単に達成することが出来ます。一つの規則が複数の HTTP メソッドをサポートする場合は、メソッド名をカンマで区切ります。
例えば、次の三つの規則は、`post/<id:\d+>` という同一のパターンを持って、異なる HTTP メソッドをサポートするものです。
`PUT post/100` に対するリクエストは `post/create` と解析され、`GET post/100` に対するリクエストは `post/view`
と解析されることになります。
503 504 505 506 507 508 509 510 511

```php
[
    'PUT,POST post/<id:\d+>' => 'post/create',
    'DELETE post/<id:\d+>' => 'post/delete',
    'post/<id:\d+>' => 'post/view',
]
```

512 513
> Note|注意: URL 規則が HTTP メソッドをパターンに含む場合、その規則は解析目的にだけ使用されます。[[yii\web\UrlManager|URL マネージャ]]
  が URL 生成のために呼ばれたときは、その規則はスキップされます。
514

515 516 517
> Tip|ヒント: RESTful API のルーティングを簡単にするために、Yii は特別な URL 規則クラス [[yii\rest\UrlRule]] を提供しています。
  これは非常に効率的なもので、コントローラ ID の自動的な複数形化など、いくつかの素敵な機能をサポートするものです。
  詳細については、RESTful API 開発についての [ルーティング](rest-routing.md) の節を参照してください。
518 519


520
### 規則をカスタマイズする <a name="customizing-rules"></a>
521

522 523 524 525
これまでの例では、URL 規則は主として「パターン - ルート」のペアの形で宣言されています。これが通常使用される短縮形式です。
特定のシナリオの下では、[[yii\web\UrlRule::suffix]] などのような、他のプロパティを構成して URL 規則をカスタマイズしたいことも
あるでしょう。完全なコンフィギュレーション配列を使って規則を指定すれば、そうすることが出来ます。次の例は、[URL 接尾辞](#url-suffixes)
の項から抜き出したものです。
526 527 528

```php
[
529
    // ... 他の URL 規則 ...
530 531 532 533 534 535 536 537 538
    
    [
        'pattern' => 'posts',
        'route' => 'post/index',
        'suffix' => '.json',
    ],
]
```

539
> Info|情報: 規則のコンフィギュレーションで `class` を指定しない場合は、既定として、[[yii\web\UrlRule]] クラスが使われます。
540 541
  

542
### 規則を動的に追加する <a name="adding-rules"></a>
543

544 545 546 547 548
URL 規則は [[yii\web\UrlManager|URL マネージャ]] に動的に追加することが出来ます。このことは、再配布可能な [モジュール](structure-modules.md)
が自分自身の URL 規則を管理する必要がある場合に、しばしば必要になります。動的に追加された規則がルーティングのプロセスで効果を発揮するためには、
その規則を [ブートストラップ](runtime-bootstrapping.md) の段階で追加しなければなりません。これは、モジュールにとっては、次のように、
[[yii\base\BootstrapInterface]] を実装して、[[yii\base\BootstrapInterface::bootstrap()|bootstrap()]]
メソッドの中で規則を追加しなければならないことを意味します。
549 550 551 552 553

```php
public function bootstrap($app)
{
    $app->getUrlManager()->addRules([
554
        // ここに規則の宣言
555 556 557 558
    ], false);
}
```

559 560
さらに、モジュールが [ブートストラップ](runtime-bootstrapping.md) の過程に関与できるように、それを [[yii\web\Application::bootstrap]]
のリストに挙げなければならないことに注意してください。
561 562


563
### 規則クラスを作成する <a name="creating-rules"></a>
564

565 566 567 568 569
デフォルトの [[yii\web\UrlRule]] クラスはほとんどのプロジェクトに対して十分に柔軟なものであるというのは事実ですが、
それでも、自分自身で規則クラスを作る必要があるような状況はあります。例えば、自動車ディーラーのウェブサイトにおいて、
`/Manufacturer/Model` のような URL 形式をサポートしたいけれども、`Manufacturer` と `Model` は、両方とも、
データベーステーブルに保存されている何らかのデータに合致するものでなければならない、というような場合です。
デフォルトの規則クラスは、静的に宣言されるパターンに依拠しているため、ここでは役に立ちません。
570

571
この問題を解決するために、次のような URL 規則クラスを作成することが出来ます。
572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598

```php
namespace app\components;

use yii\web\UrlRule;

class CarUrlRule extends UrlRule
{
    public $db = 'db';

    public function init()
    {
        parent::init();
        if ($this->name === null) {
            $this->name = __CLASS__;
        }
    }

    public function createUrl($manager, $route, $params)
    {
        if ($route === 'car/index') {
            if (isset($params['manufacturer'], $params['model'])) {
                return $params['manufacturer'] . '/' . $params['model'];
            } elseif (isset($params['manufacturer'])) {
                return $params['manufacturer'];
            }
        }
599
        return false;  // この規則は適用されない
600 601 602 603 604 605
    }

    public function parseRequest($manager, $request)
    {
        $pathInfo = $request->getPathInfo();
        if (preg_match('%^(\w+)(/(\w+))?$%', $pathInfo, $matches)) {
606 607 608 609
            // $matches[1] と $matches[3] をチェックして、
            // データベースの中の製造者とモデルに合致するかどうか調べる
            // 合致すれば、$params['manufacturer'] および/または $params['model'] をセットし、
            // ['car/index', $params] を返す
610
        }
611
        return false;  // この規則は適用されない
612 613 614 615
    }
}
```

616
そして、[[yii\web\UrlManager::rules]] のコンフィギュレーションで、新しい規則クラスを使います。
617 618 619

```php
[
620
    // ... 他の規則 ...
621 622 623
    
    [
        'class' => 'app\components\CarUrlRule', 
624
        // ... 他のプロパティを構成する ...
625 626 627 628 629
    ],
]
```


630
## パフォーマンスに対する考慮 <a name="performance-consideration"></a>
631

632 633
複雑なウェブアプリケーションを開発するときは、リクエストの解析と URL 生成に要する時間を削減するために
URL 規則を最適化することが重要になります。
634

635
パラメータ化したルートを使うことによって、URL 規則の数を減らして、パフォーマンスを著しく向上させることが出来ます。
636

637 638
URL を解析または生成するときに、[[yii\web\UrlManager|URL マネージャ]] は、宣言された順序で URL 規則を調べます。
従って、より多く使われる規則がより少なく使われる規則より前に来るように順序を調整することを検討してください。
639

640 641 642 643
パターンまたはルートに共通の先頭部分を持つ URL 規則がある場合は、[[yii\web\UrlManager|URL マネージャ]]
がそれらをグループ化して効率的に調べることが出来るように、[[yii\web\GroupUrlRule]] を使うことを検討してください。
あなたのアプリケーションがモジュールによって構成されており、モジュールごとに、モジュール ID を共通の先頭部分とする
一群の URL 規則を持っている場合は、通常、このことが当てはまります。