[MANUAL] English:
[zend.git] / documentation / manual / en / module_specs / Zend_Controller-Router-Route.xml
blob46549982c021010b92ce9abf30d523bcb59a33f8
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- Reviewed: no -->
3 <sect3 id="zend.controller.router.routes.standard">
4     <title>Zend_Controller_Router_Route</title>
6     <para>
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.
12     </para>
14     <para>
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:
20     </para>
22     <programlisting language="php"><![CDATA[
23 $route = new Zend_Controller_Router_Route(
24     'author/:username',
25     array(
26         'controller' => 'profile',
27         'action'     => 'userinfo'
28     )
31 $router->addRoute('user', $route);
32 ]]></programlisting>
34     <para>
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>.
41     </para>
43     <note>
44         <title>Character Usage</title>
46         <para>
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.
52         </para>
53     </note>
55     <para>
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:
62     </para>
64     <programlisting language="php"><![CDATA[
65 $values = array(
66     'username'   => 'martel',
67     'controller' => 'profile',
68     'action'     => 'userinfo'
70 ]]></programlisting>
72     <para>
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:
79     </para>
81     <programlisting language="php"><![CDATA[
82 public function userinfoAction()
84     $request = $this->getRequest();
85     $username = $request->getParam('username');
87     $username = $this->_getParam('username');
89 ]]></programlisting>
91     <para>
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:
96     </para>
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);
104 ]]></programlisting>
106     <sect4 id="zend.controller.router.routes.standard.variable-defaults">
107         <title>Variable Defaults</title>
109         <para>
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:
114         </para>
116         <programlisting language="php"><![CDATA[
117 $route = new Zend_Controller_Router_Route(
118     'archive/:year',
119     array('year' => 2006)
121 $router->addRoute('archive', $route);
122 ]]></programlisting>
124         <para>
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.
129         </para>
131         <para>
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:
139         </para>
141         <programlisting language="php"><![CDATA[
142 $route = new Zend_Controller_Router_Route(
143     'archive/:year',
144     array(
145         'year'       => 2006,
146         'controller' => 'archive',
147         'action'     => 'show'
148     )
150 $router->addRoute('archive', $route);
151 ]]></programlisting>
153         <para>
154             This route will then result in dispatching to the method
155             <methodname>showAction()</methodname> of the class
156             <classname>ArchiveController</classname>.
157         </para>
158     </sect4>
160     <sect4 id="zend.controller.router.routes.standard.variable-requirements">
161         <title>Variable Requirements</title>
163         <para>
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
167             expression:
168         </para>
170         <programlisting language="php"><![CDATA[
171 $route = new Zend_Controller_Router_Route(
172     'archive/:year',
173     array(
174         'year'       => 2006,
175         'controller' => 'archive',
176         'action'     => 'show'
177     ),
178     array('year' => '\d+')
180 $router->addRoute('archive', $route);
181 ]]></programlisting>
183         <para>
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.
189         </para>
190     </sect4>
192     <sect4 id="zend.controller.router.routes.standard.translated-segments">
193         <title>Translated segments</title>
195         <para>
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:
199         </para>
201         <itemizedlist>
202             <listitem>
203                 <para>
204                     Put it into the registry with the key <classname>Zend_Translate</classname>.
205                 </para>
206             </listitem>
208             <listitem>
209                 <para>
210                     Set it via the static method
211                     <methodname>Zend_Controller_Router_Route::setDefaultTranslator()</methodname>.
212                 </para>
213             </listitem>
215             <listitem>
216                 <para>
217                     Pass it as fourth parameter to the constructor.
218                 </para>
219             </listitem>
220         </itemizedlist>
222         <para>
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:
227         </para>
229         <itemizedlist>
230             <listitem>
231                 <para>
232                     Put it into the registry with the key <classname>Zend_Locale</classname>.
233                 </para>
234             </listitem>
236             <listitem>
237                 <para>
238                     Set it via the static method
239                     <methodname>Zend_Controller_Router_Route::setDefaultLocale()</methodname>.
240                 </para>
241             </listitem>
243             <listitem>
244                 <para>
245                     Pass it as fifth parameter to the constructor.
246                 </para>
247             </listitem>
249             <listitem>
250                 <para>
251                     Pass it as <command>@locale</command> parameter to the assemble
252                     method.
253                 </para>
254             </listitem>
255         </itemizedlist>
257         <para>
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.
266         </para>
268         <note>
269             <title>Message IDs and separate language file</title>
271             <para>
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.
276             </para>
277         </note>
279         <para>
280             The following is the simplest way to prepare the standard route for
281             translated segment usage:
282         </para>
284         <programlisting language="php"><![CDATA[
285 // Prepare the translator
286 $translator = new Zend_Translate(
287     array(
288         'adapter' => 'array',
289         'content' => array(),
290         'locale'  => 'en'
291     )
293 $translator->addTranslation(
294     array(
295         'content' =>
296             array(
297                 'archive' => 'archiv',
298                 'year'    => 'jahr',
299                 'month'   => 'monat',
300                 'index'   => 'uebersicht'
301             ),
302         'locale'  => 'de'
303     )
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);
311 ]]></programlisting>
313         <para>
314             This example demonstrates the usage of static segments:
315         </para>
317         <programlisting language="php"><![CDATA[
318 // Create the route
319 $route = new Zend_Controller_Router_Route(
320     '@archive',
321     array(
322         'controller' => 'archive',
323         'action'     => 'index'
324     )
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());
333 ]]></programlisting>
335         <para>
336             You can use the dynamic segments to create a module-route like
337             translated version:
338         </para>
340         <programlisting language="php"><![CDATA[
341 // Create the route
342 $route = new Zend_Controller_Router_Route(
343     ':@controller/:@action/*',
344     array(
345         'controller' => 'index',
346         'action'     => 'index'
347     )
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'));
356 ]]></programlisting>
358         <para>
359             You can also mix static and dynamic segments:
360         </para>
362         <programlisting language="php"><![CDATA[
363 // Create the route
364 $route = new Zend_Controller_Router_Route(
365     '@archive/:@mode/:value',
366     array(
367         'mode'       => 'year'
368         'value'      => 2005,
369         'controller' => 'archive',
370         'action'     => 'show'
371     ),
372     array('mode'  => '(month|year)'
373           'value' => '\d+')
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'));
382 ]]></programlisting>
383     </sect4>
384 </sect3>
385 <!--
386 vim:se ts=4 sw=4 et: