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:
'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:
'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:
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:
'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:
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:
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:
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:
'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);
]]>
This example demonstrates the usage of static segments:
'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:
'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:
'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'));
]]>