Zend_Controller_Router_Route はフレームワークの標準のルートです。 簡単に利用でき、柔軟なルート定義が可能です。各ルートには、まず (静的および動的な) URL のマッピングが含まれ、 そしてデフォルト値および変数についての制限を指定して初期化します。

とある架空のアプリケーションで、コンテンツの作者情報のページが必要になったとしましょう。 ブラウザで http://domain.com/author/martel にアクセスした際に、"martel" とかいう人についての情報を見たいわけです。 この機能を実現するためのルートは、次のようになります。

Zend_Controller_Router_Route のコンストラクタの最初のパラメータは、ルートの定義です。 これを URL にマッチさせます。ルート定義は静的な部分と動的な部分で構成され、 それをスラッシュ ('/') で連結します。 静的な部分は単なるテキスト (例. author) です。 動的な部分を変数と呼び、変数名の前にコロンをつけて (例. :username) 表します。

注意: 文字の使用法
現在の実装では、(スラッシュ以外の) 任意の文字を変数名として使用できます。しかし、 PHP の変数名として使用できる文字だけを用いることを強く推奨します。 このようにしておくことで、 将来実装が変更されたときにバグを引き起こす可能性を抑えられます。

この例のルートは、ブラウザで 'http://domain.com/author/martel' を指した際にマッチします。 この場合、すべての変数の値が Zend_Controller_Request オブジェクトに注入され、ProfileController からアクセスできるようになります。 この例が返す変数は、以下のようなキーと値のペアを持つ配列となります。

その後、Zend_Controller_Dispatcher は (デフォルトモジュールの) ProfileController クラスにある userinfoAction() メソッドを実行します。変数にアクセスするには、 Zend_Controller_Action::_getParam() あるいは Zend_Controller_Request::getParam() メソッドを使用します。

ルート定義には、特殊文字 (ワイルドカード) を含めることができます。これは '*' 記号で表します。 これを使用して、Module ルートと同様にパラメータを扱う (変数名 => 値 のペアを URI で定義する) ことができます。 次のルートは、Module ルートの挙動をまねたものです。

これまでの例では、すべて動的なルートを使用していました。 つまり、特定のパターンにマッチするものについてのルートです。 しかし、時には特定のルートを固定してしまい、 わざわざ正規表現エンジンを動かしたくない場合もあるでしょう。 そんなときには静的なルートを使用します。

上のルートは http://domain.com/login という URL にマッチし、AuthController::loginAction() にディスパッチされます。

注意: 警告: 静的なルートにはまともなデフォルトが必須
静的なルートは、URL の一部をリクエストオブジェクトへのパラメータとして渡すことはありません。 したがって、リクエストのディスパッチに必要なパラメータは すべてデフォルトでルートに渡すようにしておかなければなりません。 "controller" や "action" のデフォルト値を省略してしまうと予期せぬ結果を引き起こし、 リクエストがディスパッチ不能になってしまうでしょう。
一般に、以下のデフォルト値は常に渡すようにしておきましょう。

• controller

• action

• module (デフォルト以外の場合)

オプションで、起動時に "useDefaultControllerAlways" パラメータをフロントコントローラに渡すこともできます。

1. $front->setParam('useDefaultControllerAlways', true);

しかし、これはあくまでも次善策であり、 デフォルトを明記しておくほうがおすすめです。

デフォルトのルートや静的なルートに加えて、正規表現によるルートも使用可能です。 このルートは他のものに比べてより強力で柔軟なものですが、 多少複雑になってしまいます。そして、より高速になります。

標準のルートと同様、このルートを初期化する際にはルートの定義とデフォルトを指定する必要があります。 サンプルとして、archive ルートを作成してみましょう。 これは先ほど定義したものとほぼ同じですが、今回は Regex ルートを使用しています。

定義された正規表現のパターンが、リクエストオブジェクトに注入されます。 上の例では、http://domain.com/archive/2006 がマッチした後の結果の値は次のような配列になります。

注意: ルータとのマッチングを行う前に、URL の先頭と最後のスラッシュは取り除かれます。 結果として、URL http://domain.com/foo/bar/ は正規表現 foo/bar にマッチすることになります。 /foo/bar にはマッチしません。

注意: 行頭と行末を表す文字 (それぞれ '^' および '$') が、すべての式の前後に自動的に付加されます。 したがって、これらは正規表現で指定する必要はありません。

注意: このルートクラスは、区切り文字として # を使用します。 つまり、ルート定義の中にハッシュ文字 ('#') がある場合は、それをエスケープする必要があるということです。 スラッシュ ('/') をエスケープする必要はありません。 '#' (アンカー) は通常はウェブサーバに渡されることはないので、 エスケープが必要になることはまずないでしょう。

定義されたサブパターンの内容は、通常通りの方法で取得できます。

注意: このキーは、文字列 ('1') ではなく数値の 1 であることに注意しましょう。

このルートは、標準のルートとまったく同様に動作するわけではありません。 'year' のデフォルトが設定されていないからです。 また、year のデフォルトを設定してこれをオプション扱いにしたとしても、 最後のスラッシュをどうするかという問題が残ります。 これを解決するには、year 部をスラッシュを含めてオプションにし、 その数値部のみを取得するようにします。

まだ問題が残っていることにおそらくお気づきでしょう。 パラメータとして数値のキーを使用するのはなかなか難しく、 長い目で見れば問題を引き起こす可能性が高くなります。 そこで三番目のパラメータの登場です。 このパラメータは、正規表現サブパターンとパラメータ名のキーを関連付けます。 簡単な例を見てみましょう。

この結果は次のようになり、これがリクエストオブジェクトに格納されます。

関連付けは両方の方法で定義でき、任意の環境 (例. Zend_Config) で動作します。 キーには変数名あるいはサブパターン番号のいずれかを含めることができます。

注意: サブパターンのキーは整数値でなければなりません。

リクエストの値から数値キーが消え、代わりに名前がつけられたことに注目しましょう。 もちろん、お望みなら数値での指定と名前での指定を共用することもできます。

この結果、リクエスト内には数値キーと名前つきキーが共存することになります。 たとえば、URL http://domain.com/archive/2006/page/10 は次のような値になります。

正規表現を簡単に反転させることはできないので、 url ヘルパーやこのクラスのメソッドを使用するには 逆の URL を準備しておく必要があります。 逆方向のパスは sprintf() 形式の文字列で表し、 コンストラクタの四番目のパラメータとして指定します。

これまで説明してきたことは、すべて標準のルートオブジェクトでも可能なことです。 それでは、Regex ルートを使用するメリットはいったい何なのでしょう? これを使用すると、あらゆる形式の URL を制約なしに定義することができます。 仮に、あなたが blog を持っており http://domain.com/blog/archive/01-Using_the_Regex_Router.html のような URL を作成したいと考えたとしましょう。 このパスの最後の要素 01-Using_the_Regex_Router.html から記事の ID とタイトル/説明 を取得するにはどうしたらいいでしょうか？ 標準のルートでは不可能でしょう。Regex ルートを使用した場合は、 次のようにすることができます。

regex ルートは標準のルートよりはるかに柔軟性があるということが、 ここからもわかります。

Zend_Controller_Router_Route_Hostname はホスト名によるルートです。標準のルートと同じように動作しますが、 パスではなくコールされた URL のホスト名に基づいて動作します。

標準のルートの例を使用して、 ホスト名に基づいた動作がどのようなものになるのかを見ていきましょう。 パスを利用してユーザをコールするのではなく、たとえば http://martel.users.example.com でユーザ "martel" の情報を見られるようにしたいものとします。

Zend_Controller_Router_Route_Hostname のコンストラクタの最初のパラメータはルートの定義で、 これがホスト名にマッチします。 ルート定義には静的な部分と動的な部分があり、両者はドット ('.') で区切られています。動的な部分 (変数) は、変数名の先頭にコロンをつけて :username のように表します。静的な部分は、user のように単純なテキストで表します。

hostname ルートを単独で使うこともできますが、決してしてはいけません。 その理由は、hostname ルートはそれ単体だと任意のパスにマッチすることになるからです。 hostname ルートの後には path ルートをつなげなければなりません。 例に示したように、$hostnameRoute->chain($pathRoute); のようにコールすることになります。こうすると、 $hostnameRoute には何も変更は加えられませんが、新たなルート (Zend_Controller_Router_Route_Chain) が返されます。 そして、これをルータに渡します。

Zend_Controller_Router_Route_Chain is a route which allows to chain multiple routes together. This allows you to chain hostname-routes and path routes, or multiple path routes for example. Chaining can be done either programatically or within a configuration file.

注意: Parameter Priority
When chaining routes together, the parameters of the outer route have a higher priority than the parameters of the inner route. Thus if you define a controller in the outer and in the inner route, the controller of the outer route will be selected.

When chaining programatically, there are two ways to achieve this. The first one is to create a new Zend_Controller_Router_Route_Chain instance and then calling the chain method multiple times with all routes which should be chained together. The other way is to take the first route, e.g. a hostname route, and calling the chain method on it with the route which should be appended to it. This will not modify the hostname route, but return a new instance of Zend_Controller_Router_Route_Chain, which then has both routes chained together:

// Create two routes
$hostnameRoute = new Zend_Controller_Router_Route_Hostname(...);
$pathRoute     = new Zend_Controller_Router_Route(...);

// First way, chain them via the chain route
$chainedRoute = new Zend_Controller_Router_Route_Chain();
$chainedRoute->chain($hostnameRoute)
             ->chain($pathRoute);

// Second way, chain them directly
$chainedRoute = $hostnameRoute->chain($pathRoute);

When chaining routes together, their default separator is a slash by default. There may be cases when you want to have a different separator:

// Create two routes
$firstRoute  = new Zend_Controller_Router_Route('foo');
$secondRoute = new Zend_Controller_Router_Route('bar');

// Chain them together with a different separator
$chainedRoute = $firstRoute->chain($secondRoute, '-');

// Assemble the route: "foo-bar"
echo $chainedRoute->assemble();

<routes>
    <www type="Zend_Controller_Router_Route_Hostname">
        <route>www.example.com</route>
        <chains>
            <language type="Zend_Controller_Router_Route">
                <route>:language</route>
                <reqs language="[a-z]{2}">
                <chains>
                    <index type="Zend_Controller_Router_Route_Static">
                        <route></route>
                        <defaults module="default" controller="index" action="index" />
                    </index>
                    <imprint type="Zend_Controller_Router_Route_Static">
                        <route>imprint</route>
                        <defaults module="default" controller="index" action="index" />
                    </imprint>
                </chains>
            </language>
        </chains>
    </www>
    <users type="Zend_Controller_Router_Route_Hostname">
        <route>users.example.com</route>
        <chains>
            <profile type="Zend_Controller_Router_Route">
                <route>:username</route>
                <defaults module="users" controller="profile" action="index" />
            </profile>
        </chains>
    </users>
    <misc type="Zend_Controller_Router_Route_Static">
        <route>misc</route>
    </misc>
</routes>

<routes>
    <www type="Zend_Controller_Router_Route_Chain">
        <route>www.example.com</route>
    </www>
    <language type="Zend_Controller_Router_Route">
        <route>:language</route>
        <reqs language="[a-z]{2}">
    </language>
    <index type="Zend_Controller_Router_Route_Static">
        <route></route>
        <defaults module="default" controller="index" action="index" />
    </index>
    <imprint type="Zend_Controller_Router_Route_Static">
        <route>imprint</route>
        <defaults module="default" controller="index" action="index" />
    </imprint>

    <www-index type="Zend_Controller_Router_Route_Chain">
        <chain>www, language, index</chain>
    </www-index>
    <www-imprint type="Zend_Controller_Router_Route_Chain">
        <chain>www, language, imprint</chain>
    </www-imprint>
</routes>

<routes>
    <www-index type="Zend_Controller_Router_Route_Chain">
        <chain>www</chain>
        <chain>language</chain>
        <chain>index</chain>
    </www-index>
    <www-imprint type="Zend_Controller_Router_Route_Chain">
        <chain>www</chain>
        <chain>language</chain>
        <chain>imprint</chain>
    </www-imprint>
</routes>