5日目: ルーティング

4日目を完璧にこなしているなら、MVC パターンに慣れてきて、コーディング方法がより自然に感じるようになっていることでしょう。もっと時間をかけて学ぶことで、振り返らないようになるでしょう。昨日のチュートリアルで、Jobeet のページデザインや処理のカスタマイズをし、レイアウトやヘルパー、スロットといった symfony のコンセプトについても見直しました。

今日は、symfony のルーティングフレームワークのすばらしい世界に飛び込みましょう。

URL

Jobeet ホームページ上の求人情報をクリックすると、URL は /job/show/id/1 のように表示されます。もし PHP で Web サイトの開発をしたことがあるなら、おそらく /job.php?id=1 という URL を見慣れているでしょう。symfony はどうやって動作しているのでしょうか？symfony はどうやってこの URL を基本とするアクションを決めているのでしょうか？なぜ求人の id は $request->getParameter('id') で得ることができるのでしょうか？今日は、これらすべての問題の答えを見てゆきます。

しかしまず初めに、URL と URL が正確に指すものについて話します。Web コンテキスト上で、URL は Web リソースの一意性のある名前です。URL の先へ行くと、ブラウザに URL によって分類されているリソースを取得するように頼みます。そして URL は Web サイトとユーザー間のインターフェイスとして、リソースが参照している意味のある情報を伝えます。しかし旧来の URL は実際にはリソースについての説明をしておらず、アプリケーションの内部構造を公開してしまっています。ユーザーは Web サイトが PHP で開発されているとか、求人情報がもつデータベースのある識別子というようなことはあまり気にしません。アプリケーションの内部動作を公開することはセキュリティの観点から見ても、非常にまずいことです。ユーザーが URL 先にアクセスすることなくリソースを予想することができたらどうだろうか？開発者は適切な方法でアプリをセキュアすべきで、機密情報は隠したほうがよいです。 URL は symfony でフレームワーク全体を管理するのに重要なものです。これはルーティング (routing) フレームワークで管理します。ルーティングは内部 URI と外部 URL を管理します。リクエストを受け取るとき、ルーティングは URL を解析して内部URIに変換します。

求人ページの内部 URI はすでに indexSuccess.php テンプレートで見ています:

'job/show?id='.$job->getId()

url_for() ヘルパーはこの内部 URI を適切な URL に変換します:

/job/show/id/1

内部 URI はいくつかのパーツから構成されます。job はモジュール名で、show はアクション名、その後にアクションに渡すパラメータをクエリ文字列として追加します。内部 URI の一般的なパターンを下記に示します:

MODULE/ACTION?key=value&key_1=value_1&...

symfony のルーティングは2つの処理方法があるので、技術的実装を変更することなく URL を変換することができます。このことは Front Controller デザインパターンの主な利点の1つです。

ルーティングコンフィギュレーション

内部 URI と外部 URL 間のマッピングは routing.yml ファイルで行われます:

# apps/frontend/config/routing.yml
homepage:
  url:   /
  param: { module: default, action: index }
 
default_index:
  url:   /:module
  param: { action: index }
 
default:
  url:   /:module/:action/*

routing.yml はルートについて記述されています。ルートは名前 (homepage)、パターン (/:module/:action/*) といくつかのパラメータ (param キー下の値) をもちます。

リクエストが来るとき、URL から得られるパターンにマッチするかを試します。routing.yml のなかの最初にマッチするルートが重要となります。このルーティングの動作を理解するためにもっとたくさんの例を見ることにしましょう。

/job の URL をもつ Jobeet ホームページにリクエストをすると、マッチする最初のルートは default_index です。パターンのなかでは、コロン (:) をプレフィックスとする単語が変数であり、/:module パターンは「/ の後にマッチする何か」ということを意味します。この例のなかでは、module 変数は値として job をもちます。この値は $request->getParameter('module') で取得することができます。このルートは action 変数にはデフォルト値が定義されます。

よってこのルートにマッチするすべてのの URL のリクエストは action パラメータには index という値をもつようになります。

もし /job/show/id/1 ページにリクエストするなら、symfony は最後のパターンである (/:modules/:action/*) にマッチします。

パターン内ではスター (*) はスラッシュ (/) で区切られる変数と値のペアの一群にマッチします:

URL の /job/show/id/1 は下記で使われている url_for() ヘルパーによってテンプレートから作られます:

url_for('job/show?id='.$job->getId())

@ をプレフィックスとするルート名も使えます:

url_for('@default?module=job&action=show&id='.$job->getId())

上記2つは同じものですが、後者の方がすべてのルートを解析することなくベストなマッチングをするため速く動作しますし、実装する上でもより少ないコードになります (モジュール名、アクション名を内部 URI 内に含まないので)。

ルートのカスタマイズ

今のところ、ブラウザで URL の / にリクエストすると、symfony のデフォルトの初期ページになります。その理由はこのURLが homepage ルートにマッチするからです。しかし Jobeet のホームページとしての役割を果たすように変更します。変更するには、homepage ルートの module 変数の値を job に変更します:

# apps/frontend/config/routing.yml
homepage:
  url:   /
  param: { module: job, action: index }

homepage ルートを使うように、レイアウトのなかの Jobeet ロゴのリンクを変更します:

<!-- apps/frontend/templates/layout.php -->
<h1>
  <a href="<?php echo url_for('homepage') ?>">
    <img src="/legacy/images/logo.jpg" alt="Jobeet Job Board" />
  </a>
</h1>

簡単でした！

もう少し内容を含めるために、求人ページの URL をより意味のある文字列に変更してみましょう:

/job/sensio-labs/paris-france/1/web-developer

Jobeet についての知識がなくても、ページをみなくても、URL から Sensio Labs がフランスのパリで Web 開発者を探しているということがわかります。

URL を下記のようなパターンにマッチさせます:

/job/:company/:location/:id/:position

routing.yml ファイルを編集し、ファイルの冒頭に job_show_user ルートを追加します:

job_show_user:
  url:   /job/:company/:location/:id/:position
  param: { module: job, action: show }

Jobeet ホームページをリフレッシュしても、求人情報へのリンクは変更されません。ルートを生成するなら、必要な変数をすべて渡すことが必要となります。ですので、indexSuccess.php のなかで呼び出される url_for() を変更する必要があります。

url_for('job/show?id='.$job->getId().'&company='.$job->getCompany().
  '&location='.$job->getLocation().'&position='.$job->getPosition())

内部 URI は配列として表すこともできます:

url_for(array(
  'module'   => 'job',
  'action'   => 'show',
  'id'       => $job->getId(),
  'company'  => $job->getCompany(),
  'location' => $job->getLocation(),
  'position' => $job->getPosition(),
))

要件

初日のチュートリアルのあいだ、よい結果をもたらすバリデーションとエラーハンドリングについて話しました。ルーティングシステムは組み込みのバリデーション機能をもちます。各パターンの変数はルート定義のなかの requirements エントリを使って正規表現によるバリデーションができます。

job_show_user:
  url:   /job/:company/:location/:id/:position
  param: { module: job, action: show }
  requirements:
    id: \d+

上記の requirements エントリは id が数値であることを強制しています。もし数値でなければルートにはマッチしません。

ルートクラス

routing.yml で定義されている各ルートは内部で sfRoute オブジェクトに変換されます。このクラスはルート定義の class エントリで定義することで変更可能です。HTTP プロトコルをよく知っているのなら、~GET|GET (HTTP メソッド)~、~POST|POST (HTTP メソッド)~、~HEAD|HEAD (HTTP メソッド)~、~DELETE|DELETE (HTTP メソッド)~ と ~PUT|PUT (HTTP メソッド)~ のようなメソッドを定義することもできます。 最初の3つ (GET、POST、HEAD) はすべてのブラウザでサポートされますが、それ以外の2つ (DELETE、PUT) はサポートされていません。

特定のリクエストメソッドだけにマッチするようルートを制限するには、sfRequestRoute クラスを使うようにルートクラスを変更して、sf_method 変数を requirements エントリに追加できます:

job_show_user:
  url:   /job/:company/:location/:id/:position
  class: sfRequestRoute
  param: { module: job, action: show }
  requirements:
    id: \d+
    sf_method: [get]

オブジェクトルートクラス

求人用の新しい内部 URI はとても長くて書くのが退屈ですが (url_for('job/show?id='.$job->getId().'&company='.$job->getCompany().'&location='.$job->getLocation().'&position='.$job->getPosition()))、前の節で学んだように、ルートクラスは変更できます。job_show_user ルートに関しては、sfDoctrineRoute を使うほうがよいです。このクラスが Doctrine オブジェクトもしくは Doctrine オブジェクトのコレクションを表すルートに合わせて最適化されているからです:

job_show_user:
  url:     /job/:company/:location/:id/:position
  class:   sfDoctrineRoute
  options: { model: JobeetJob, type: object }
  param:   { module: job, action: show }
  requirements:
    id: \d+
    sf_method: [get]

options エントリはルートのふるまいをカスタマイズします。ここでは、model オプションはルートに関係する Doctrine モデルクラス (JobeetJob) を定義し、type オプションでは、このルートに関係するオブジェクトを定義します (オブジェクトの一群を示すなら list も使えます)。

job_show_user ルートは JobeetJob オブジェクトの関係を知らないので、url_for() ヘルパーで呼び出すのは簡単です:

url_for(array('sf_route' => 'job_show_user', 'sf_subject' => $job))

もしくは単に次のように記述します:

url_for('job_show_user', $job)

ルートのなかのすべての変数は JobeetJob クラスのアクセサと対応して動きます (たとえば、company ルートの変数は getCampany() の値に置き換わります)。

生成された URL を見ると、これらはまだ完全にほしい URL にはなっていません:

http://jobeet.localhost/frontend_dev.php/job/Sensio+Labs/Paris%2C+France/1/Web+Developer

すべての ASCII ではない文字をハイフン (-) に置き換えることで、カラム値の値を 「slugify」処理 する必要があります。JobeetJob ファイルを開き、次のメソッドをクラスに追加してください:

// lib/model/doctrine/JobeetJob.class.php
public function getCompanySlug()
{
  return Jobeet::slugify($this->getCompany());
}
 
public function getPositionSlug()
{
  return Jobeet::slugify($this->getPosition());
}
 
public function getLocationSlug()
{
  return Jobeet::slugify($this->getLocation());
}

それから、lib/Jobeet.class.php ファイルを作り、slugify メソッドを追加します:

// lib/Jobeet.class.php
class Jobeet
{
  static public function slugify($text)
  {
    // 文字ではないもしくは数値ではないものすべてを - に置き換える
    $text = preg_replace('/\W+/', '-', $text);
 
    // トリムして小文字に変換する
    $text = strtolower(trim($text, '-'));
 
    return $text;
  }
}

「バーチャルな」3つの新しいアクセサ: getCompanySlug()、getPositionSlug()、と getLocationSlug() を定義しました。これらは slugify() メソッドに適用した後で対応するカラムの値を返します。job_show_user ルートでこれらのバーチャルアクセサで実際のカラムの名前を置き換えることができます:

job_show_user:
  url:     /job/:company_slug/:location_slug/:id/:position_slug
  class:   sfDoctrineRoute
  options: { model: JobeetJob, type: object }
  param:   { module: job, action: show }
  requirements:
    id: \d+
    sf_method: [get]

これで期待する URL が利用できるようになります:

http://jobeet.localhost/frontend_dev.php/job/sensio-labs/paris-france/1/web-developer

しかしこれは話の半分です。ルートはオブジェクトに基づいて URL を生成できますが、渡された URL に関連するオブジェクトを見つけることもできます。関連オブジェクトはルートオブジェクトの getObject() メソッドで読み取ることができます。やってくるリクエストを解析する際に、ルーティングはアクションで使うためにマッチするルートオブジェクトを保存します。Jobeet オブジェクトを読み取るためにルートオブジェクトを使う executeShow() メソッドを変更します:

class jobActions extends sfActions
{
  public function executeShow(sfWebRequest $request)
  {
    $this->job = $this->getRoute()->getObject();
 
    $this->forward404Unless($this->job);
  }
 
  // ...
}

もし未知の id の求人情報を取得しようとするなら404エラーページが表示されますが、エラーメッセージが変更されているでしょう:

この理由は404エラーが getRoute() メソッドによって自動的に投げられるからです。ですので executeShow() メソッドはもっと単純にできます:

class jobActions extends sfActions
{
  public function executeShow(sfWebRequest $request)
  {
    $this->job = $this->getRoute()->getObject();
  }
 
  // ...
}

アクションとテンプレートにおけるルーティング

テンプレートでは url_for() ヘルパーは内部 URI を外部 URL に変換します。その他の symfony ヘルパーのなかにも、引数として内部 URI をもつものがあります。<a> タグを生成する link_to() ヘルパーがその1つです:

<?php echo link_to($job->getPosition(), 'job_show_user', $job) ?>

下記のような HTML コードを生成します:

<a href="/job/sensio-labs/paris-france/1/web-developer">Web Developer</a>

url_for() と link_to() の両方とも絶対パスでも URL を生成できます:

url_for('job_show_user', $job, true);
 
link_to($job->getPosition(), 'job_show_user', $job, true);

アクションから URL を生成したいなら、generateUrl() メソッドを使います:

$this->redirect($this->generateUrl('job_show_user', $job));

コレクションルートクラス

job モジュールに関して、show アクションのルートはすでにカスタマイズしていますが、その他のメソッド (index、 new、edit、create、update、delete) の URL はまだ default ルートで管理されています:

default:
  url: /:module/:action/*

default ルートは多くのルートを定義しなくても、コーディングを始められるすばらしい方法です。しかし「すべてのアクションをキャッチ」してしまうので固有の設定が必要でも設定できません。

すべての job アクションは JobeetJob モデルクラスに関連しており、show アクションに対してすべて行っているので、それぞれに対してカスタムの sfDoctrineRoute ルートを簡単に定義できます。

job モジュールはモデルのために古典的な7つのアクションを定義するので、sfDoctrineRouteCollection クラスも使えます。

routing.yml ファイルを開き、次のように修正します:

# apps/frontend/config/routing.yml
job:
  class:   sfDoctrineRouteCollection
  options: { model: JobeetJob }
 
job_show_user:
  url:     /job/:company_slug/:location_slug/:id/:position_slug
  class:   sfDoctrineRoute
  options: { model: JobeetJob, type: object }
  param:   { module: job, action: show }
  requirements:
    id: \d+
    sf_method: [get]
 
# default rules
homepage:
  url:   /
  param: { module: job, action: index }
 
default_index:
  url:   /:module
  param: { action: index }
 
default:
  url:   /:module/:action/*

上記の job ルートは実際には下記に示す7つの sfDoctrineRoute ルートを自動的に生成します:

job:
  url:     /job.:sf_format
  class:   sfDoctrineRoute
  options: { model: JobeetJob, type: list }
  param:   { module: job, action: index, sf_format: html }
  requirements: { sf_method: get }
 
job_new:
  url:     /job/new.:sf_format
  class:   sfDoctrineRoute
  options: { model: JobeetJob, type: object }
  param:   { module: job, action: new, sf_format: html }
  requirements: { sf_method: get }
 
job_create:
  url:     /job.:sf_format
  class:   sfDoctrineRoute
  options: { model: JobeetJob, type: object }
  param:   { module: job, action: create, sf_format: html }
  requirements: { sf_method: post }
 
job_edit:
  url:     /job/:id/edit.:sf_format
  class:   sfDoctrineRoute
  options: { model: JobeetJob, type: object }
  param:   { module: job, action: edit, sf_format: html }
  requirements: { sf_method: get }
 
job_update:
  url:     /job/:id.:sf_format
  class:   sfDoctrineRoute
  options: { model: JobeetJob, type: object }
  param:   { module: job, action: update, sf_format: html }
  requirements: { sf_method: put }
 
job_delete:
  url:     /job/:id.:sf_format
  class:   sfDoctrineRoute
  options: { model: JobeetJob, type: object }
  param:   { module: job, action: delete, sf_format: html }
  requirements: { sf_method: delete }
 
job_show:
  url:     /job/:id.:sf_format
  class:   sfDoctrineRoute
  options: { model: JobeetJob, type: object }
  param:   { module: job, action: show, sf_format: html }
  requirements: { sf_method: get }

job_delete と job_update ルートが必要とする HTTP メソッドはブラウザでサポートされていません (~DELETE|DELETE (HTTP メソッド)~ と ~PUT|PUT (HTTP メソッド)~)。この動作は symfony がシミュレートしているので動きます。具体例を見るために _form.php テンプレートを開いてください:

// apps/frontend/modules/job/templates/_form.php
<form action="..." ...>
<?php if (!$form->getObject()->isNew()): ?>
  <input type="hidden" name="sf_method" value="PUT" />
<?php endif; ?>
 
<?php echo link_to(
  'Delete',
  'job/delete?id='.$form->getObject()->getId(),
  array('method' => 'delete', 'confirm' => 'Are you sure?')
) ?>

特別な sf_method パラメータを渡すことで、すべての symfony ヘルパーに望む HTTP メソッドをシミュレートするように指示できます。

ルートのデバッグ

コレクションルートを使うなら、生成されるルートの一覧の表示が役に立つことがあります。app:routes タスクはアプリケーションから得られたすべてのルートを出力します:

$ php symfony app:routes frontend

引数にルート名を追加することで、指定したルートに関するたくさんのデバッグ情報を取得できます:

$ php symfony app:routes frontend job_edit

デフォルトルート

すべての URL に対してルートを定義するのはよい習慣です。job ルートは Jobeet アプリケーションを記述するために必要なすべてのルールを定義するので、routing.yml 設定ファイルからデフォルトのルートを削除もしくはコメントアウトします:

# apps/frontend/config/routing.yml
#default_index:
#  url:   /:module
#  param: { action: index }
#
#default:
#  url:   /:module/:action/*

Jobeet アプリケーションは以前と同じように動作します。

また明日

今日はたくさんの情報を詰め込みました。symfony のルーティングフレームワークの使い方と URL を技術的な実装から分離する方法を学びました。

明日は、新しい概念を紹介しませんが、これまでカバーしてきたことをより深く追求することに時間をかけます。