1 <?xml version="1.0" encoding="UTF-8"?>
3 <sect3 id="zend.controller.router.routes.standard">
4 <title>Zend_Controller_Router_Route</title>
7 <classname>Zend_Controller_Router_Route</classname> is the standard framework
8 route. It combines ease of use with flexible route definition. Each
9 route consists primarily of <acronym>URL</acronym> mapping (of static and dynamic parts
10 (variables)) and may be initialized with defaults as well as with
11 variable requirements.
15 Let's imagine our fictional application will need some informational
16 page about the content authors. We want to be able to point our web
17 browsers to <filename>http://domain.com/author/martel</filename> to see the
18 information about this "martel" guy. And the route for such
19 functionality could look like:
22 <programlisting language="php"><![CDATA[
23 $route = new Zend_Controller_Router_Route(
26 'controller' => 'profile',
27 'action' => 'userinfo'
31 $router->addRoute('user', $route);
35 The first parameter in the <classname>Zend_Controller_Router_Route</classname>
36 constructor is a route definition that will be matched to a <acronym>URL</acronym>. Route
37 definitions consist of static and dynamic parts separated by the slash
38 ('/') character. Static parts are just simple text:
39 <command>author</command>. Dynamic parts, called variables, are marked by
40 prepending a colon to the variable name: <command>:username</command>.
44 <title>Character Usage</title>
47 The current implementation allows you to use any character (except a
48 slash) as a variable identifier, but it is strongly recommended that
49 one uses only characters that are valid for <acronym>PHP</acronym> variable
50 identifiers. Future implementations may alter this behaviour, which
51 could result in hidden bugs in your code.
56 This example route should be matched when you point your browser to
57 <filename>http://domain.com/author/martel</filename>, in which case all its
58 variables will be injected to the <classname>Zend_Controller_Request</classname>
59 object and will be accessible in your <classname>ProfileController</classname>.
60 Variables returned by this example may be represented as an array of
61 the following key and value pairs:
64 <programlisting language="php"><![CDATA[
66 'username' => 'martel',
67 'controller' => 'profile',
68 'action' => 'userinfo'
73 Later on, <classname>Zend_Controller_Dispatcher_Standard</classname> should invoke
74 the <methodname>userinfoAction()</methodname> method of your
75 <classname>ProfileController</classname> class (in the default module) based on
76 these values. There you will be able to access all variables by means of
77 the <methodname>Zend_Controller_Action::_getParam()</methodname> or
78 <methodname>Zend_Controller_Request::getParam()</methodname> methods:
81 <programlisting language="php"><![CDATA[
82 public function userinfoAction()
84 $request = $this->getRequest();
85 $username = $request->getParam('username');
87 $username = $this->_getParam('username');
92 Route definition can contain one more special character - a wildcard
93 - represented by '*' symbol. It is used to gather parameters similarly
94 to the default Module route (var => value pairs defined in the <acronym>URI</acronym>). The
95 following route more-or-less mimics the Module route behavior:
98 <programlisting language="php"><![CDATA[
99 $route = new Zend_Controller_Router_Route(
100 ':module/:controller/:action/*',
101 array('module' => 'default')
103 $router->addRoute('default', $route);
106 <sect4 id="zend.controller.router.routes.standard.variable-defaults">
107 <title>Variable Defaults</title>
110 Every variable in the route can have a default and this is what the
111 second parameter of the <classname>Zend_Controller_Router_Route</classname>
112 constructor is used for. This parameter is an array with keys
113 representing variable names and with values as desired defaults:
116 <programlisting language="php"><![CDATA[
117 $route = new Zend_Controller_Router_Route(
119 array('year' => 2006)
121 $router->addRoute('archive', $route);
125 The above route will match <acronym>URL</acronym>s like
126 <filename>http://domain.com/archive/2005</filename> and
127 <filename>http://example.com/archive</filename>. In the latter case the
128 variable year will have an initial default value of 2006.
132 This example will result in injecting a year variable to the request
133 object. Since no routing information is present (no controller and
134 action parameters are defined), the application will be dispatched
135 to the default controller and action method (which are both defined
136 in <classname>Zend_Controller_Dispatcher_Abstract</classname>). To make it
137 more usable, you have to provide a valid controller and a valid
138 action as the route's defaults:
141 <programlisting language="php"><![CDATA[
142 $route = new Zend_Controller_Router_Route(
146 'controller' => 'archive',
150 $router->addRoute('archive', $route);
154 This route will then result in dispatching to the method
155 <methodname>showAction()</methodname> of the class
156 <classname>ArchiveController</classname>.
160 <sect4 id="zend.controller.router.routes.standard.variable-requirements">
161 <title>Variable Requirements</title>
164 One can add a third parameter to the
165 <classname>Zend_Controller_Router_Route</classname> constructor where variable
166 requirements may be set. These are defined as parts of a regular
170 <programlisting language="php"><![CDATA[
171 $route = new Zend_Controller_Router_Route(
175 'controller' => 'archive',
178 array('year' => '\d+')
180 $router->addRoute('archive', $route);
184 With a route defined like above, the router will match it only when
185 the year variable will contain numeric data, eg.
186 <filename>http://domain.com/archive/2345</filename>. A <acronym>URL</acronym> like
187 <filename>http://example.com/archive/test</filename> will not be matched and
188 control will be passed to the next route in the chain instead.
192 <sect4 id="zend.controller.router.routes.standard.translated-segments">
193 <title>Translated segments</title>
196 The standard route supports translated segments. To use this
197 feature, you have to define at least a translator (an instance
198 of <classname>Zend_Translate</classname>) via one of the following ways:
204 Put it into the registry with the key <classname>Zend_Translate</classname>.
210 Set it via the static method
211 <methodname>Zend_Controller_Router_Route::setDefaultTranslator()</methodname>.
217 Pass it as fourth parameter to the constructor.
223 By default, the locale specified in the <classname>Zend_Translate</classname>
224 instance will be used. To override it, you set it
225 (an instance of <classname>Zend_Locale</classname> or a locale string) in one
226 of the following ways:
232 Put it into the registry with the key <classname>Zend_Locale</classname>.
238 Set it via the static method
239 <methodname>Zend_Controller_Router_Route::setDefaultLocale()</methodname>.
245 Pass it as fifth parameter to the constructor.
251 Pass it as <command>@locale</command> parameter to the assemble
258 Translated segments are separated into two parts. Fixed segments
259 are prefixed by a single <emphasis>@</emphasis>-sign, and will be
260 translated to the current locale when assembling and reverted
261 to the message ID when matching again. Dynamic segments
262 are prefixed by <command>:@</command>. When assembling, the given
263 parameter will be translated and inserted into the parameter
264 position. When matching, the translated parameter from the
265 <acronym>URL</acronym> will be reverted to the message ID again.
269 <title>Message IDs and separate language file</title>
272 Occasionally a message ID which you want to use in one
273 of your routes is already used in a view script or somewhere
274 else. To have full control over safe <acronym>URL</acronym>s, you should use
275 a separate language file for the messages used in the route.
280 The following is the simplest way to prepare the standard route for
281 translated segment usage:
284 <programlisting language="php"><![CDATA[
285 // Prepare the translator
286 $translator = new Zend_Translate(
288 'adapter' => 'array',
289 'content' => array(),
293 $translator->addTranslation(
297 'archive' => 'archiv',
300 'index' => 'uebersicht'
306 // Set the current locale for the translator
307 $translator->setLocale('en');
309 // Set it as default translator for routes
310 Zend_Controller_Router_Route::setDefaultTranslator($translator);
314 This example demonstrates the usage of static segments:
317 <programlisting language="php"><![CDATA[
319 $route = new Zend_Controller_Router_Route(
322 'controller' => 'archive',
326 $router->addRoute('archive', $route);
328 // Assemble the URL in default locale: archive
329 $route->assemble(array());
331 // Assemble the URL in german: archiv
332 $route->assemble(array());
336 You can use the dynamic segments to create a module-route like
340 <programlisting language="php"><![CDATA[
342 $route = new Zend_Controller_Router_Route(
343 ':@controller/:@action/*',
345 'controller' => 'index',
349 $router->addRoute('archive', $route);
351 // Assemble the URL in default locale: archive/index/foo/bar
352 $route->assemble(array('controller' => 'archive', 'foo' => 'bar'));
354 // Assemble the URL in german: archiv/uebersicht/foo/bar
355 $route->assemble(array('controller' => 'archive', 'foo' => 'bar'));
359 You can also mix static and dynamic segments:
362 <programlisting language="php"><![CDATA[
364 $route = new Zend_Controller_Router_Route(
365 '@archive/:@mode/:value',
369 'controller' => 'archive',
372 array('mode' => '(month|year)'
375 $router->addRoute('archive', $route);
377 // Assemble the URL in default locale: archive/month/5
378 $route->assemble(array('mode' => 'month', 'value' => '5'));
380 // Assemble the URL in german: archiv/monat/5
381 $route->assemble(array('mode' => 'month', 'value' => '5', '@locale' => 'de'));