routing.yml について: 基本と応用

最近 Symfony framework で開発するようになりました。まだ使いこなしていない部分も数多くありますが、とても便利です。

中でも今日は Askeet チュートリアル 4 日目: リファクタリング などで紹介されている routing.yml についてすこし解説しておきたいと思います。

基本

routing.yml はアプリケーション内での URL の規約を設定するファイルです。以下のような特徴があります。

• まず mod_rewrite かまたはそれに準ずるものがホストとなる HTTP Server にインストールされていて、正しく設定されている事が必要です。dev 環境では動いても、prod 環境では動かない、（というか HTTP Server 独自の 404 File Not Found がでる）と言う場合は RewriteBase を設定してうまくいくことが多いようです（Apache の場合）。例えば、httpd.conf の Alias をつかって http://example.com/askeet/ みたいな形で site root でないところを Symfony の web directory につないだ時には、当たり前かもしれませんが RewriteBase の設定が必要です。
• routing.yml 抜きのまっさらな状態では、Symfony の frontend controller は Symfony web root 以下の URL 文字列を /（forward slash）で区切ります。それの奇数番目を key に、偶数番目を value にした array を作って、それを以降のアクションなどに Request Parameters として渡します。
  つまり、もし http://example.com/askeet に Symfony web directory が map してあって、ユーザが http://example.com/askeet/foo/bar/hoge/huga/123/456 とリクエストしてきた場合は、[ foo => bar, hoge => huga, 123 => 456 ] という風なリクエストが出来るわけです。
• デフォルトで、4つ、ルールが書かれています。これらは、したければ自分で変更したってかまいません。そしてこれらには順番には意味があります（順番は後述）。
• Symfony の frontend controller は、引数（つまり directory 区切り記号）の数をかぞえているようです。数とパターンが両方一致した、上から数えて一番最初のルールを適用するようです。
• パターンにおいて、文字列はそのままの一致。:label のように : (colon) で始めると、"label" を key とし、ユーザの送った内容を value とする array をつくり request parameter に保持されます。* (asterisk) はワイルドカードで、それのあるエントリでは、引数の数は関係なく、* 以降はあってもなくても関係なくなります。また * 以降の値は基本通り、奇数番目が key に、偶数番目が value になる request parameters を作ります。
  例えばでフォルトエントリの一つの以下を参考にすると…

  default_symfony:
    url:   /symfony/:action/*
    param: { module: default }

  1. Symfony web root より最初の引数が symfony という値で、
  2. 第二の奇数をアクションとして
  3. それ以降の値は奇数/偶数→key/value
  という風に解釈されます。例えば先ほどの例と同じ設定のサイトに http://example.com/askeet/symfony/admin/foo/bar/123/456 というリクエストを出すと、module: default, action: admin に [ foo => bar, 123 => 456 ] というリクエストパラメータを投げます。
• :module と :action だけは特殊なラベルで、他には使えないようです。

応用

リクエストの時、

1. 何も値がなかったら、全ての値を返し、
2. 引数が２つ以上あったら、最初の２つをキーにした値を返し、
3. それ以外は 404

とかはよくありそうな話です。先ほどの例と同じく、http://example.com/askeet に symfony web directory がmap されているとしましょう。まずは正解から

part:
 url:    /api/list/:id1/:id2/*
 param:  { module: api, action: list }

error:
 url:    /api/list/:id1/*
 param:  { module: api, action: list }

all:
 url:    /api/list/*
 param:  { module: api, action: list }

大事なのは api_list_error の項目が api_list よりも後に定義されているという事ですね。あと error と all の両方のエントリの最後が * で終わっている事。そうしないと、例えば http://example.com/askeet で来たのは拾えても、 http://example.com/askeet/ で来たのは拾えません。

そして受け取るアクションでは、以下のようなコードを書くといいかもしれません。

$req1 = $this->getRequestParameter('id1');
$req2 = $this->getRequestParameter('id2');

switch (true) 
{
  case (is_null($req1) && is_null($req2)):
    $result = "all";
    break;

  case (isset($req1) && isset($req2)):
    $result = "partial select";
    break;

  default:
    $this->forward404();
    break;
}

まとめ

routing.yml について解説しました。順番が大事であるという事、* をつける事の有無などの考察は何となくわかっていても、書き出してみる事で自分中でもすっきりまとまりました。

参考

• The Definitive Guide to symfony Chapter 9 - Links And The Routing System
• branches/1.0/lib/controller/sfRouting.class.php
  しっかり読み込んでないけれど、504 行目から始まる parse という method がここで解説している処理部分の様子。