# Zend_Controller_Router_Route

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

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 `http://domain.com/author/martel` to see the information about this "martel" guy. And the route for such functionality could look like:

    $route = new Zend_Controller_Router_Route(
        'author/:username',
        array(
            'controller' => 'profile',
            'action'     => 'userinfo'
        )
    );

    $router->addRoute('user', $route);

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

## Character Usage

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 PHP variable identifiers. Future implementations may alter this behaviour, which could result in hidden bugs in your code.

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

    $values = array(
        'username'   => 'martel',
        'controller' => 'profile',
        'action'     => 'userinfo'
    );

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

    public function userinfoAction()
    {
        $request = $this->getRequest();
        $username = $request->getParam('username');

        $username = $this->_getParam('username');
    }

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 URI). The following route more-or-less mimics the Module route behavior:

    $route = new Zend_Controller_Router_Route(
        ':module/:controller/:action/*',
        array('module' => 'default')
    );
    $router->addRoute('default', $route);

## Variable Defaults

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

    $route = new Zend_Controller_Router_Route(
        'archive/:year',
        array('year' => 2006)
    );
    $router->addRoute('archive', $route);

The above route will match URLs like `http://domain.com/archive/2005` and `http://example.com/archive`. In the latter case the variable year will have an initial default value of 2006.

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 `Zend_Controller_Dispatcher_Abstract`). To make it more usable, you have to provide a valid controller and a valid action as the route's defaults:

    $route = new Zend_Controller_Router_Route(
        'archive/:year',
        array(
            'year'       => 2006,
            'controller' => 'archive',
            'action'     => 'show'
        )
    );
    $router->addRoute('archive', $route);

This route will then result in dispatching to the method `showAction()` of the class `ArchiveController`.

## Variable Requirements

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

    $route = new Zend_Controller_Router_Route(
        'archive/:year',
        array(
            'year'       => 2006,
            'controller' => 'archive',
            'action'     => 'show'
        ),
        array('year' => '\d+')
    );
    $router->addRoute('archive', $route);

With a route defined like above, the router will match it only when the year variable will contain numeric data, eg. `http://domain.com/archive/2345`. A URL like `http://example.com/archive/test` will not be matched and control will be passed to the next route in the chain instead.

## Translated segments

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

- Put it into the registry with the key `Zend_Translate`.

- Set it via the static method `Zend_Controller_Router_Route::setDefaultTranslator()`.

- Pass it as fourth parameter to the constructor.

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

- Put it into the registry with the key `Zend_Locale`.

- Set it via the static method `Zend_Controller_Router_Route::setDefaultLocale()`.

- Pass it as fifth parameter to the constructor.

- Pass it as `@locale` parameter to the assemble method.

Translated segments are separated into two parts. Fixed segments are prefixed by a single @-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 `:@`. When assembling, the given parameter will be translated and inserted into the parameter position. When matching, the translated parameter from the URL will be reverted to the message ID again.

### Message IDs and separate language file

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 URLs, you should use a separate language file for the messages used in the route.

The following is the simplest way to prepare the standard route for translated segment usage:

    // Prepare the translator
    $translator = new Zend_Translate('array', array(), 'en');
    $translator->addTranslation(array('archive' => 'archiv',
                                      'year'    => 'jahr',
                                      'month'   => 'monat',
                                      'index'   => 'uebersicht'),
                                'de');

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

    // Set it as default translator for routes
    Zend_Controller_Router_Route::setDefaultTranslator($translator);

This example demonstrates the usage of static segments:

    // 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());

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

    // 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'));

You can also mix static and dynamic segments:

    // 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'));