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

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

    <para>
        <classname>Zend_Controller_Router_Route</classname> is the standard framework
        route. It combines ease of use with flexible route definition. Each
        route consists primarily of <acronym>URL</acronym> mapping (of static and dynamic parts
        (variables)) and may be initialized with defaults as well as with
        variable requirements.
    </para>

    <para>
        Let's imagine our fictional application will need some informational
        page about the content authors. We want to be able to point our web
        browsers to <filename>http://domain.com/author/martel</filename> to see the
        information about this "martel" guy. And the route for such
        functionality could look like:
    </para>

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

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

    <para>
        The first parameter in the <classname>Zend_Controller_Router_Route</classname>
        constructor is a route definition that will be matched to a <acronym>URL</acronym>. Route
        definitions consist of static and dynamic parts separated by the slash
        ('/') character. Static parts are just simple text:
        <command>author</command>. Dynamic parts, called variables, are marked by
        prepending a colon to the variable name: <command>:username</command>.
    </para>

    <note>
        <title>Character Usage</title>

        <para>
            The current implementation allows you to use any character (except a
            slash) as a variable identifier, but it is strongly recommended that
            one uses only characters that are valid for <acronym>PHP</acronym> variable
            identifiers. Future implementations may alter this behaviour, which
            could result in hidden bugs in your code.
        </para>
    </note>

    <para>
        This example route should be matched when you point your browser to
        <filename>http://domain.com/author/martel</filename>, in which case all its
        variables will be injected to the <classname>Zend_Controller_Request</classname>
        object and will be accessible in your <classname>ProfileController</classname>.
        Variables returned by this example may be represented as an array of
        the following key and value pairs:
    </para>

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

    <para>
        Later on, <classname>Zend_Controller_Dispatcher_Standard</classname> should invoke
        the <methodname>userinfoAction()</methodname> method of your
        <classname>ProfileController</classname> class (in the default module) based on
        these values. There you will be able to access all variables by means of
        the <methodname>Zend_Controller_Action::_getParam()</methodname> or
        <methodname>Zend_Controller_Request::getParam()</methodname> methods:
    </para>

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

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

    <para>
        Route definition can contain one more special character - a wildcard
        - represented by '*' symbol. It is used to gather parameters similarly
        to the default Module route (var => value pairs defined in the <acronym>URI</acronym>). The
        following route more-or-less mimics the Module route behavior:
    </para>

    <programlisting language="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>Variable Defaults</title>

        <para>
            Every variable in the route can have a default and this is what the
            second parameter of the <classname>Zend_Controller_Router_Route</classname>
            constructor is used for. This parameter is an array with keys
            representing variable names and with values as desired defaults:
        </para>

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

        <para>
            The above route will match <acronym>URL</acronym>s like
            <filename>http://domain.com/archive/2005</filename> and
            <filename>http://example.com/archive</filename>. In the latter case the
            variable year will have an initial default value of 2006.
        </para>

        <para>
            This example will result in injecting a year variable to the request
            object. Since no routing information is present (no controller and
            action parameters are defined), the application will be dispatched
            to the default controller and action method (which are both defined
            in <classname>Zend_Controller_Dispatcher_Abstract</classname>). To make it
            more usable, you have to provide a valid controller and a valid
            action as the route's defaults:
        </para>

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

        <para>
            This route will then result in dispatching to the method
            <methodname>showAction()</methodname> of the class
            <classname>ArchiveController</classname>.
        </para>
    </sect4>

    <sect4 id="zend.controller.router.routes.standard.variable-requirements">
        <title>Variable Requirements</title>

        <para>
            One can add a third parameter to the
            <classname>Zend_Controller_Router_Route</classname> constructor where variable
            requirements may be set. These are defined as parts of a regular
            expression:
        </para>

        <programlisting language="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>
            With a route defined like above, the router will match it only when
            the year variable will contain numeric data, eg.
            <filename>http://domain.com/archive/2345</filename>. A <acronym>URL</acronym> like
            <filename>http://example.com/archive/test</filename> will not be matched and
            control will be passed to the next route in the chain instead.
        </para>
    </sect4>

    <sect4 id="zend.controller.router.routes.standard.translated-segments">
        <title>Translated segments</title>

        <para>
            The standard route supports translated segments. To use this
            feature, you have to define at least a translator (an instance
            of <classname>Zend_Translate</classname>) via one of the following ways:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    Put it into the registry with the key <classname>Zend_Translate</classname>.
                </para>
            </listitem>

            <listitem>
                <para>
                    Set it via the static method
                    <methodname>Zend_Controller_Router_Route::setDefaultTranslator()</methodname>.
                </para>
            </listitem>

            <listitem>
                <para>
                    Pass it as fourth parameter to the constructor.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            By default, the locale specified in the <classname>Zend_Translate</classname>
            instance will be used. To override it, you set it
            (an instance of <classname>Zend_Locale</classname> or a locale string) in one
            of the following ways:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    Put it into the registry with the key <classname>Zend_Locale</classname>.
                </para>
            </listitem>

            <listitem>
                <para>
                    Set it via the static method
                    <methodname>Zend_Controller_Router_Route::setDefaultLocale()</methodname>.
                </para>
            </listitem>

            <listitem>
                <para>
                    Pass it as fifth parameter to the constructor.
                </para>
            </listitem>

            <listitem>
                <para>
                    Pass it as <command>@locale</command> parameter to the assemble
                    method.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Translated segments are separated into two parts. Fixed segments
            are prefixed by a single <emphasis>@</emphasis>-sign, and will be
            translated to the current locale when assembling and reverted
            to the message ID when matching again. Dynamic segments
            are prefixed by <command>:@</command>. When assembling, the given
            parameter will be translated and inserted into the parameter
            position. When matching, the translated parameter from the
            <acronym>URL</acronym> will be reverted to the message ID again.
        </para>

        <note>
            <title>Message IDs and separate language file</title>

            <para>
                Occasionally a message ID which you want to use in one
                of your routes is already used in a view script or somewhere
                else. To have full control over safe <acronym>URL</acronym>s, you should use
                a separate language file for the messages used in the route.
            </para>
        </note>

        <para>
            The following is the simplest way to prepare the standard route for
            translated segment usage:
        </para>

        <programlisting language="php"><![CDATA[
// Prepare the translator
$translator = new Zend_Translate(
    array(
        'adapter' => 'array',
        'content' => array(),
        'locale'  => 'en'
    )
);
$translator->addTranslation(
    array(
        'content' =>
            array(
                'archive' => 'archiv',
                'year'    => 'jahr',
                'month'   => 'monat',
                'index'   => 'uebersicht'
            ),
        'locale'  => 'de'
    )
);

// Set the current locale for the translator
$translator->setLocale('en');

// Set it as default translator for routes
Zend_Controller_Router_Route::setDefaultTranslator($translator);
]]></programlisting>

        <para>
            This example demonstrates the usage of static segments:
        </para>

        <programlisting language="php"><![CDATA[
// Create the route
$route = new Zend_Controller_Router_Route(
    '@archive',
    array(
        'controller' => 'archive',
        'action'     => 'index'
    )
);
$router->addRoute('archive', $route);

// Assemble the URL in default locale: archive
$route->assemble(array());

// Assemble the URL in german: archiv
$route->assemble(array());
]]></programlisting>

        <para>
            You can use the dynamic segments to create a module-route like
            translated version:
        </para>

        <programlisting language="php"><![CDATA[
// Create the route
$route = new Zend_Controller_Router_Route(
    ':@controller/:@action/*',
    array(
        'controller' => 'index',
        'action'     => 'index'
    )
);
$router->addRoute('archive', $route);

// Assemble the URL in default locale: archive/index/foo/bar
$route->assemble(array('controller' => 'archive', 'foo' => 'bar'));

// Assemble the URL in german: archiv/uebersicht/foo/bar
$route->assemble(array('controller' => 'archive', 'foo' => 'bar'));
]]></programlisting>

        <para>
            You can also mix static and dynamic segments:
        </para>

        <programlisting language="php"><![CDATA[
// Create the route
$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);

// Assemble the URL in default locale: archive/month/5
$route->assemble(array('mode' => 'month', 'value' => '5'));

// Assemble the URL in german: archiv/monat/5
$route->assemble(array('mode' => 'month', 'value' => '5', '@locale' => 'de'));
]]></programlisting>
    </sect4>
</sect3>
<!--
vim:se ts=4 sw=4 et:
-->