# Zend_Controller_Router_Route_Regex

In addition to the default and static route types, a Regular Expression route type is available. This route offers more power and flexibility over the others, but at a slight cost of complexity. At the same time, it should be faster than the standard Route.

Like the standard route, this route has to be initialized with a route definition and some defaults. Let's create an archive route as an example, similar to the previously defined one, only using the Regex route this time:

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

Every defined regex subpattern will be injected to the request object. With our above example, after successful matching `http://domain.com/archive/2006`, the resulting value array may look like:

    $values = array(
        1            => '2006',
        'controller' => 'archive',
        'action'     => 'show'
    );

Leading and trailing slashes are trimmed from the URL in the Router prior to a match. As a result, matching the URL `http://domain.com/foo/bar/`, would involve a regex of `foo/bar`, and not `/foo/bar`.

Line start and line end anchors ('^' and '$', respectively) are automatically pre- and appended to all expressions. Thus, you should not use these in your regular expressions, and you should match the entire string.

This route class uses the '#' character for a delimiter. This means that you will need to escape hash characters ('#') but not forward slashes ('/') in your route definitions. Since the '#' character (named anchor) is rarely passed to the webserver, you will rarely need to use that character in your regex.

You can get the contents of the defined subpatterns the usual way:

    public function showAction()
    {
        $request = $this->getRequest();
        $year    = $request->getParam(1); // $year = '2006';
    }

Notice the key is an integer (1) instead of a string ('1').

This route will not yet work exactly the same as its standard route counterpart since the default for 'year' is not yet set. And what may not yet be evident is that we will have a problem with a trailing slash even if we declare a default for the year and make the subpattern optional. The solution is to make the whole year part optional along with the slash but catch only the numeric part:

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

Now let's get to the problem you have probably noticed on your own by now. Using integer based keys for parameters is not an easily manageable solution and may be potentially problematic in the long run. And that's where the third parameter comes in. This parameter is an associative array that represents a map of regex subpatterns to parameter named keys. Let's work on our easier example:

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

This will result in following values injected into Request:

    $values = array(
        'year'       => '2006',
        'controller' => 'archive',
        'action'     => 'show'
    );

The map may be defined in either direction to make it work in any environment. Keys may contain variable names or subpattern indexes:

    $route = new Zend_Controller_Router_Route_Regex(
        'archive/(\d+)',
        array( ... ),
        array(1 => 'year')
    );

    // OR

    $route = new Zend_Controller_Router_Route_Regex(
        'archive/(\d+)',
        array( ... ),
        array('year' => 1)
    );

Subpattern keys have to be represented by integers.

Notice that the numeric index in Request values is now gone and a named variable is shown in its place. Of course you can mix numeric and named variables if you wish:

    $route = new Zend_Controller_Router_Route_Regex(
        'archive/(\d+)/page/(\d+)',
        array( ... ),
        array('year' => 1)
    );

Which will result in mixed values available in the Request. As an example, the URL `http://domain.com/archive/2006/page/10` will result in following values:

    $values = array(
        'year'       => '2006',
        2            => 10,
        'controller' => 'archive',
        'action'     => 'show'
    );

Since regex patterns are not easily reversed, you will need to prepare a reverse URL if you wish to use a URL helper or even an assemble method of this class. This reversed path is represented by a string parsable by `sprintf()` and is defined as a fourth construct parameter:

    $route = new Zend_Controller_Router_Route_Regex(
        'archive/(\d+)',
        array( ... ),
        array('year' => 1),
        'archive/%s'
    );

All of this is something which was already possible by the means of a standard route object, so where's the benefit in using the Regex route, you ask? Primarily, it allows you to describe any type of URL without any restrictions. Imagine you have a blog and wish to create URLs like: `http://domain.com/blog/archive/01-Using_the_Regex_Router.html`, and have it decompose the last path element, `01-Using_the_Regex_Router.html`, into an article ID and article title or description; this is not possible with the standard route. With the Regex route, you can do something like the following solution:

    $route = new Zend_Controller_Router_Route_Regex(
        'blog/archive/(\d+)-(.+)\.html',
        array(
            'controller' => 'blog',
            'action'     => 'view'
        ),
        array(
            1 => 'id',
            2 => 'description'
        ),
        'blog/archive/%d-%s.html'
    );
    $router->addRoute('blogArchive', $route);

As you can see, this adds a tremendous amount of flexibility over the standard route.