documentation/manual/en/module_specs/Zend_Controller-Router-Route-Chain.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect3 id="zend.controller.router.routes.chain">
   4     <title>Zend_Controller_Router_Route_Chain</title>
   5
   6     <para>
   7         <classname>Zend_Controller_Router_Route_Chain</classname> is a route which allows
   8         to chain multiple routes together. This allows you to chain
   9         hostname-routes and path routes, or multiple path routes for example.
  10         Chaining can be done either programatically or within a configuration
  11         file.
  12     </para>
  13
  14     <note>
  15         <title>Parameter Priority</title>
  16
  17         <para>
  18             When chaining routes together, the parameters of the outer route
  19             have a higher priority than the parameters of the inner route. Thus
  20             if you define a controller in the outer and in the inner route,
  21             the controller of the outer route will be selected.
  22         </para>
  23     </note>
  24
  25     <para>
  26         When chaining programatically, there are two ways to achieve this. The
  27         first one is to create a new
  28         <classname>Zend_Controller_Router_Route_Chain</classname> instance and then
  29         calling the <methodname>chain()</methodname> method multiple times with all routes
  30         which should be chained together. The other way is to take the first
  31         route, e.g. a hostname route, and calling the <methodname>chain()</methodname>
  32         method on it with the route which should be appended to it. This
  33         will not modify the hostname route, but return a new instance of
  34         <classname>Zend_Controller_Router_Route_Chain</classname>, which then has both
  35         routes chained together:
  36     </para>
  37
  38     <programlisting language="php"><![CDATA[
  39 // Create two routes
  40 $hostnameRoute = new Zend_Controller_Router_Route_Hostname(...);
  41 $pathRoute     = new Zend_Controller_Router_Route(...);
  42
  43 // First way, chain them via the chain route
  44 $chainedRoute = new Zend_Controller_Router_Route_Chain();
  45 $chainedRoute->chain($hostnameRoute)
  46              ->chain($pathRoute);
  47
  48 // Second way, chain them directly
  49 $chainedRoute = $hostnameRoute->chain($pathRoute);
  50 ]]></programlisting>
  51
  52     <para>
  53         When chaining routes together, their separator is a slash
  54         by default. There may be cases when you want to have a different
  55         separator:
  56     </para>
  57
  58     <programlisting language="php"><![CDATA[
  59 // Create two routes
  60 $firstRoute  = new Zend_Controller_Router_Route('foo');
  61 $secondRoute = new Zend_Controller_Router_Route('bar');
  62
  63 // Chain them together with a different separator
  64 $chainedRoute = $firstRoute->chain($secondRoute, '-');
  65
  66 // Assemble the route: "foo-bar"
  67 echo $chainedRoute->assemble();
  68 ]]></programlisting>
  69
  70     <sect4 id="zend.controller.router.routes.chain.config">
  71         <title>Chain Routes via Zend_Config</title>
  72
  73         <para>
  74             To chain routes together in a config file, there are additional
  75             parameters for the configuration of those. The simpler approach is
  76             to use the <property>chains</property> parameters. This one is simply a list
  77             of routes, which will be chained with the parent route. Neither the
  78             parent- nor the child-route will be added directly to the router but
  79             only the resulting chained route. The name of the chained route in
  80             the router will be the parent route name and the child route name
  81             concatenated with a dash (-) by default. A simple config in <acronym>XML</acronym>
  82             would look like this:
  83         </para>
  84
  85         <programlisting language="xml"><![CDATA[
  86 <routes>
  87     <www type="Zend_Controller_Router_Route_Hostname">
  88         <route>www.example.com</route>
  89         <chains>
  90             <language type="Zend_Controller_Router_Route">
  91                 <route>:language</route>
  92                 <reqs language="[a-z]{2}">
  93                 <chains>
  94                     <index type="Zend_Controller_Router_Route_Static">
  95                         <route></route>
  96                         <defaults module="default" controller="index"
  97                                   action="index" />
  98                     </index>
  99                     <imprint type="Zend_Controller_Router_Route_Static">
 100                         <route>imprint</route>
 101                         <defaults module="default" controller="index"
 102                                   action="index" />
 103                     </imprint>
 104                 </chains>
 105             </language>
 106         </chains>
 107     </www>
 108     <users type="Zend_Controller_Router_Route_Hostname">
 109         <route>users.example.com</route>
 110         <chains>
 111             <profile type="Zend_Controller_Router_Route">
 112                 <route>:username</route>
 113                 <defaults module="users" controller="profile" action="index" />
 114             </profile>
 115         </chains>
 116     </users>
 117     <misc type="Zend_Controller_Router_Route_Static">
 118         <route>misc</route>
 119     </misc>
 120 </routes>
 121 ]]></programlisting>
 122
 123         <para>
 124             This will result in the three routes <command>www-language-index</command>,
 125             <command>www-language-imprint</command> and
 126             <command>users-language-profile</command> which will only match based on
 127             the hostname and the route <command>misc</command>, which will match with
 128             any hostname.
 129         </para>
 130
 131         <para>
 132             The alternative way of creating a chained route is via the
 133             <property>chain</property> parameter, which can only be used with the
 134             chain-route type directly, and also just works in the root level:
 135         </para>
 136
 137         <programlisting language="xml"><![CDATA[
 138 <routes>
 139     <www type="Zend_Controller_Router_Route_Chain">
 140         <route>www.example.com</route>
 141     </www>
 142     <language type="Zend_Controller_Router_Route">
 143         <route>:language</route>
 144         <reqs language="[a-z]{2}">
 145     </language>
 146     <index type="Zend_Controller_Router_Route_Static">
 147         <route></route>
 148         <defaults module="default" controller="index" action="index" />
 149     </index>
 150     <imprint type="Zend_Controller_Router_Route_Static">
 151         <route>imprint</route>
 152         <defaults module="default" controller="index" action="index" />
 153     </imprint>
 154
 155     <www-index type="Zend_Controller_Router_Route_Chain">
 156         <chain>www, language, index</chain>
 157     </www-index>
 158     <www-imprint type="Zend_Controller_Router_Route_Chain">
 159         <chain>www, language, imprint</chain>
 160     </www-imprint>
 161 </routes>
 162 ]]></programlisting>
 163
 164         <para>
 165             You can also give the <property>chain</property> parameter as array instead
 166             of separating the routes with a comma:
 167         </para>
 168
 169         <programlisting language="xml"><![CDATA[
 170 <routes>
 171     <www-index type="Zend_Controller_Router_Route_Chain">
 172         <chain>www</chain>
 173         <chain>language</chain>
 174         <chain>index</chain>
 175     </www-index>
 176     <www-imprint type="Zend_Controller_Router_Route_Chain">
 177         <chain>www</chain>
 178         <chain>language</chain>
 179         <chain>imprint</chain>
 180     </www-imprint>
 181 </routes>
 182 ]]></programlisting>
 183
 184         <para>
 185             When you configure chain routes with <classname>Zend_Config</classname> and
 186             want the chain name separator to be different from a dash, you
 187             need to specify this separator separately:
 188         </para>
 189
 190         <programlisting language="php"><![CDATA[
 191 $config = new Zend_Config(array(
 192     'chainName' => array(
 193         'type'   => 'Zend_Controller_Router_Route_Static',
 194         'route'  => 'foo',
 195         'chains' => array(
 196             'subRouteName' => array(
 197                 'type'     => 'Zend_Controller_Router_Route_Static',
 198                 'route'    => 'bar',
 199                 'defaults' => array(
 200                     'module'      => 'module',
 201                      'controller' => 'controller',
 202                      'action'     => 'action'
 203                 )
 204             )
 205         )
 206     )
 207 ));
 208
 209 // Set separator before adding config
 210 $router->setChainNameSeparator('_separator_')
 211
 212 // Add config
 213 $router->addConfig($config);
 214
 215 // The name of our route now is: chainName_separator_subRouteName
 216 echo $this->_router->assemble(array(), 'chainName_separator_subRouteName');
 217
 218 // The proof: it echoes /foo/bar
 219 ]]></programlisting>
 220     </sect4>
 221 </sect3>
 222 <!--
 223 vim:se ts=4 sw=4 et:
 224 -->