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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 15103 -->
<sect3 id="zend.controller.router.routes.standard">
    <title>Zend_Controller_Router_Route</title>

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

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

    <programlisting role="php"><![CDATA[
$route = new Zend_Controller_Router_Route(
    'author/:username',
    array(
        'controller' => 'profile',
        'action'     => 'userinfo'
    )
);

$router->addRoute('user', $route);
]]>
    </programlisting>

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

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

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

    <programlisting role="php"><![CDATA[
$values = array(
    'username'   => 'martel',
    'controller' => 'profile',
    'action'     => 'userinfo'
);
]]>
    </programlisting>

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

    <programlisting role="php"><![CDATA[
public function userinfoAction()
{
    $request = $this->getRequest();
    $username = $request->getParam('username');

    $username = $this->_getParam('username');
}
]]>
    </programlisting>

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

    <programlisting role="php"><![CDATA[
$route = new Zend_Controller_Router_Route(
    ':module/:controller/:action/*',
    array('module' => 'default')
);
$router->addRoute('default', $route);
]]>
    </programlisting>

    <sect4 id="zend.controller.router.routes.standard.variable-defaults">
        <title>変数のデフォルト</title>

        <para>
            ルートで使用するすべての変数についてデフォルト値を指定することができます。
            これは、 <classname>Zend_Controller_Router_Route</classname>
            のコンストラクタの 2 番目のパラメータで指定します。
            このパラメータは、変数名をキーとする配列で、
            対応する値にそのデフォルト値を指定します。
        </para>

        <programlisting role="php"><![CDATA[
$route = new Zend_Controller_Router_Route(
    'archive/:year',
    array('year' => 2006)
);
$router->addRoute('archive', $route);
]]>
        </programlisting>

        <para>
            上のルートは <code>'http://domain.com/archive/2005'</code> および
            <code>'http://example.com/archive'</code>
            のような URL にマッチします。後者の場合、変数 year にはデフォルト値である
            2006 が設定されます。
        </para>

        <para>
            この例は、year 変数をリクエストオブジェクトに注入することになります。
            そしてルーティング情報が存在しない
            (コントローラやアクションのパラメータが定義されていない) ので、
            アプリケーションはデフォルトのコントローラのデフォルトアクションメソッド
            (ともに <classname>Zend_Controller_Dispatcher_Abstract</classname> で定義されています)
            にディスパッチします。より使いやすくするには、
            ルートのデフォルトとしてコントローラとアクションを定義しておく必要があります。
        </para>

        <programlisting role="php"><![CDATA[
$route = new Zend_Controller_Router_Route(
    'archive/:year',
    array(
        'year'       => 2006,
        'controller' => 'archive',
        'action'     => 'show'
    )
);
$router->addRoute('archive', $route);
]]>
        </programlisting>

        <para>
            このルートは、<code>ArchiveController</code> の
            <code>showAction()</code> を実行します。
        </para>

    </sect4>

    <sect4 id="zend.controller.router.routes.standard.variable-requirements">
        <title>変数の制約</title>

        <para>
            <classname>Zend_Controller_Router_Route</classname> のコンストラクタの
            三番目のパラメータで、変数の制約を指定することができます。
            これは、正規表現で指定します。
        </para>

        <programlisting role="php"><![CDATA[
$route = new Zend_Controller_Router_Route(
    'archive/:year',
    array(
        'year'       => 2006,
        'controller' => 'archive',
        'action'     => 'show'
    ),
    array('year' => '\d+')
);
$router->addRoute('archive', $route);
]]>
        </programlisting>

        <para>
            上の例のルートでは、year 変数の値が数値データである場合にのみ
            Rewrite ルータにマッチします。つまり
            <code>http://domain.com/archive/2345</code> はマッチしますが
            <code>http://example.com/archive/test</code> はマッチしません。
            この場合はチェイン内の次のルートに処理を移します。
        </para>
    </sect4>

    <sect4 id="zend.controller.router.routes.standard.translated-segments">
        <title>翻訳済みセグメント</title>

        <para>
            標準のルートは、翻訳済みセグメントをサポートします。この機能を使用するには、
            次のいずれかの方法で翻訳器 (<classname>Zend_Translate</classname> のインスタンス)
            を定義しなければなりません。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    レジストリに、キー <classname>Zend_Translate</classname> で格納する
                </para>
            </listitem>
            <listitem>
                <para>
                    静的メソッド
                    <classname>Zend_Controller_Router_Route::setDefaultTranslator()</classname> で設定する
                </para>
            </listitem>
            <listitem>
                <para>
                    コンストラクタの 4 番目のパラメータとして渡す
                </para>
            </listitem>
        </itemizedlist>

        <para>
            デフォルトでは、<classname>Zend_Translate</classname>
            のインスタンスで指定したロケールを使用します。これを上書きするには、
            (<classname>Zend_Locale</classname> のインスタンスあるいはロケール文字列で)
            次のいずれかの方法で設定します。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    レジストリに、キー <classname>Zend_Locale</classname> で格納する
                </para>
            </listitem>
            <listitem>
                <para>
                    静的メソッド
                    <classname>Zend_Controller_Router_Route::setDefaultLocale()</classname> で設定する
                </para>
            </listitem>
            <listitem>
                <para>
                    コンストラクタの 5 番目のパラメータとして渡す
                </para>
            </listitem>
            <listitem>
                <para>
                    アセンブルメソッドのパラメータ <code>@locale</code> として渡す
                </para>
            </listitem>
        </itemizedlist>

        <para>
            翻訳済みセグメントはふたつの部分に分かれます。
            固定セグメントの前には <code>@</code> 記号がひとつつき、
            アセンブル時に現在のロケールに翻訳され、
            マッチングの際にはメッセージ ID に戻されます。
            動的セグメントの前には <code>:@</code> がつきます。
            アセンブルの際に、指定したパラメータが翻訳され、
            パラメータの位置に挿入されます。
            マッチングの際には、URL の翻訳済みパラメータが
            メッセージ ID に戻されます。
        </para>

        <note>
            <title>メッセージ ID と分割された言語ファイル</title>
            <para>
                ルートの中で使いたいメッセージ ID が、
                ビュースクリプトやその他の部分ですでに使われていることもあるでしょう。
                URL の安全性を確保するには、
                ルートで使用するメッセージを別の言語ファイルに分割しなければなりません。
            </para>
        </note>

        <para>
            標準のルートで翻訳済みセグメントを使用するための準備として
            もっともシンプルな方法は、次のようになります。
        </para>

        <programlisting role="php"><![CDATA[
// 翻訳器を準備します
$translator = new Zend_Translate('array', array(), 'en');
$translator->addTranslation(array('archive' => 'archiv',
                                  'year'    => 'jahr',
                                  'month'   => 'monat',
                                  'index'   => 'uebersicht'),
                            'de');

// 現在のロケールを翻訳器に設定します
$translator->setLocale('en');

// ルートのデフォルト翻訳器として設定します
Zend_Controller_Router_Route::setDefaultTranslator($translator);
]]>
        </programlisting>

        <para>
            これは、静的セグメントを使用する例です。
        </para>

        <programlisting role="php"><![CDATA[
// ルートを作成します
$route = new Zend_Controller_Router_Route(
    '@archive',
    array(
        'controller' => 'archive',
        'action'     => 'index'
    )
);
$router->addRoute('archive', $route);

// URL をデフォルトのロケールでアセンブルします: archive
$route->assemble(array());

// URL をドイツ語でアセンブルします: archiv
$route->assemble(array());
]]>
        </programlisting>

        <para>
            動的セグメントを使用すると、
            モジュールルートの翻訳済みバージョンを作ることができます。
        </para>

        <programlisting role="php"><![CDATA[
// ルートを作成します
$route = new Zend_Controller_Router_Route(
    ':@controller/:@action/*',
    array(
        'controller' => 'index',
        'action'     => 'index'
    )
);
$router->addRoute('archive', $route);

// URL をデフォルトのロケールでアセンブルします: archive/index/foo/bar
$route->assemble(array('controller' => 'archive', 'foo' => 'bar'));

// URL をドイツ語でアセンブルします: archiv/uebersicht/foo/bar
$route->assemble(array('controller' => 'archive', 'foo' => 'bar'));
]]>
        </programlisting>

        <para>
            静的セグメントと動的セグメントを同時に使用することもできます。
        </para>

        <programlisting role="php"><![CDATA[
// ルートを作成します
$route = new Zend_Controller_Router_Route(
    '@archive/:@mode/:value',
    array(
        'mode'       => 'year'
        'value'      => 2005,
        'controller' => 'archive',
        'action'     => 'show'
    ),
    array('mode'  => '(month|year)'
          'value' => '\d+')
);
$router->addRoute('archive', $route);

// URL をデフォルトのロケールでアセンブルします: archive/month/5
$route->assemble(array('mode' => 'month', 'value' => '5'));

// URL をドイツ語でアセンブルします: archiv/monat/5
$route->assemble(array('mode' => 'month', 'value' => '5', '@locale' => 'de'));
]]>
        </programlisting>
    </sect4>
</sect3>
<!--
vim:se ts=4 sw=4 et:
-->