documentation/manual/zh/module_specs/Zend_Controller-Router.xml

   1 <sect1 id="zend.controller.router"  xmlns:xi="http://www.w3.org/2001/XInclude">
   2     <title>标准路由器</title>
   3     <sect2 id="zend.controller.router.introduction">
   4         <title>简介</title>
   5         <para>
   6             <code>Zend_Controller_Router_Rewrite</code>是标准的框架路由器。路由是个过程，在这个过程中它取出URI的端点（跟着基本URL的URI的那部分）并把它分解成参数来决定哪个模块、哪个控制器和控制器中的哪个动作应该接受请求。模块、控制器、动作和其它参数被打包到<code>Zend_Controller_Request_Http</code>对象，接着这个对象由<code>Zend_Controller_Dispatcher_Standard</code>来处理。路由只发生一次：当请求最初被接收和第一个控制器被派遣之前。
   7         </para>
   8
   9         <para>
  10             <code>Zend_Controller_Router_Rewrite</code>被设计来考虑使用纯php结构时mod_rewrite-like的功能性。它非常宽松地基于Ruby on Rails并且不要求任何先前的web服务器URL rewriting的知识。它被设计来和单个Apache的 mod_rewrite规则（其中之一）一起工作：
  11         </para>
  12
  13         <programlisting role="php"><![CDATA[
  14 RewriteEngine on
  15 RewriteRule !\.(js|ico|gif|jpg|png|css)$ index.php
  16 ]]>
  17         </programlisting>
  18
  19         <para>
  20             或者：
  21         </para>
  22
  23         <programlisting role="php"><![CDATA[
  24 RewriteEngine on
  25 RewriteCond %{SCRIPT_FILENAME} !-f
  26 RewriteCond %{SCRIPT_FILENAME} !-d
  27 RewriteRule ^(.*)$ index.php/$1
  28 ]]>
  29         </programlisting>
  30
  31         <para>
  32             如果<ulink url="http://www.isapirewrite.com">Isapi_Rewrite</ulink>已经用下列的rewrite规则被安装为一个Isapi扩展， rewrite路由器也可以和IIS web服务器一起使用：
  33         </para>
  34
  35         <programlisting role="php"><![CDATA[
  36 RewriteRule ^[\w/\%]*(?:\.(?!(?:js|ico|gif|jpg|png|css)$)[\w\%]*$)? /index.php [I]
  37 ]]>
  38         </programlisting>
  39
  40         <note>
  41             <title>IIS Isapi_Rewrite</title>
  42             <para>
  43                 当使用IIS，<code>$_SERVER['REQUEST_URI']</code>将要么不存在，要么被设置成一个空串。在这个例子中，<code>Zend_Controller_Request_Http</code>将企图使用被Isapi_Rewrite扩展设置的<code>$_SERVER['HTTP_X_REWRITE_URL']</code>的值。
  44             </para>
  45         </note>
  46
  47         <para>
  48             如果使用 Lighttpd，下面的 rewrite 规则有效：
  49         </para>
  50
  51         <programlisting role="lighttpd"><![CDATA[
  52 url.rewrite-once = (
  53     ".*\?(.*)$" => "/index.php?$1",
  54     ".*\.(js|ico|gif|jpg|png|css)$" => "$0",
  55     "" => "/index.php"
  56 )
  57 ]]>
  58 </programlisting>
  59     </sect2>
  60
  61     <sect2 id="zend.controller.router.usage">
  62         <title>使用路由器</title>
  63
  64         <para>
  65             为正确使用rewrite路由器你必须初始化它，添加一些用户定义的路由并注入到控制器。下面的代码示例这个过程：
  66         </para>
  67
  68         <programlisting role="php"><![CDATA[
  69 // Create a router
  70
  71 $router = $ctrl->getRouter(); // returns a rewrite router by default
  72 $router->addRoute(
  73     'user',
  74     new Zend_Controller_Router_Route('user/:username',
  75                                      array('controller' => 'user',
  76                                            'action' => 'info'))
  77 );
  78 ]]>
  79         </programlisting>
  80     </sect2>
  81
  82     <sect2 id="zend.controller.router.basic">
  83         <title>基本的Rewrite路由器操作</title>
  84
  85         <para>
  86             RewriteRouter的核心是用户定义路由的定义。路由通过调用RewriteRouter的addRoute方法和传递一个由类实现的<code>Zend_Controller_Router_Route_Interface</code>的新的实例被添加。例如：
  87         </para>
  88
  89         <programlisting role="php"><![CDATA[
  90 $router->addRoute('user',
  91                   new Zend_Controller_Router_Route('user/:username'));
  92 ]]>
  93         </programlisting>
  94
  95         <para>
  96             Rewrite 路由器带有四个基本类型的路由（其中一个是特殊的）：
  97         </para>
  98
  99         <itemizedlist mark="opencircle">
 100             <listitem><para><xref linkend="zend.controller.router.routes.standard" /></para></listitem>
 101             <listitem><para><xref linkend="zend.controller.router.routes.static" /></para></listitem>
 102             <listitem><para><xref linkend="zend.controller.router.routes.regex" /></para></listitem>
 103             <listitem><para><xref linkend="zend.controller.router.default-routes" /> *</para></listitem>
 104         </itemizedlist>
 105
 106         <para>
 107             路由可以被使用无数次来创建链或用户定义的应用程序路由计划。你可以在任何配置中使用任何数量的路由，除了模块路由以外，它最好被用一次并作为通用路由（例如，作为缺省的）。每个路由将在稍后详细描述。
 108         </para>
 109
 110         <para>
 111             addRoute的第一个参数是路由名。它用来作为权柄从路由器中取得路由（例如，for URL generation purposes）。第二个参数是路由自己。
 112         </para>
 113
 114         <note>
 115             <para>
 116                 路由名最普通的用法是通过Zend_View_url助手的方法：
 117             </para>
 118
 119             <programlisting role="php"><![CDATA[
 120 "<?= $this->url(array('username' => 'martel'), 'user') ?>">Martel</a>
 121 ]]>
 122             </programlisting>
 123
 124             <para>
 125                 它将导致在 href： <code>user/martel</code>.
 126             </para>
 127         </note>
 128
 129         <para>
 130             路由是一个简单的过程，这个过程通过所有提供的路由和匹配它的当前请求的URI定义来迭代。当一个正匹配被发现，变量值从路由实例返回并注入到<code>Zend_Controller_Request</code>对象以备将来在派遣器和用户创建的控制器中使用。如果是负匹配，在链中的下个路由被检查。
 131         </para>
 132
 133         <note>
 134             <title>倒序匹配</title>
 135             <para>
 136                 用倒序来匹配路由确保最通用的路由被首先定义。
 137             </para>
 138         </note>
 139
 140         <note>
 141             <title>返回的值</title>
 142             <para>
 143                 从路由返回的值来自于URL参数或用于定义的缺省值。这些变量以后可通过<code>Zend_Controller_Request::getParam()</code> 或 <code>Zend_Controller_Action::_getParam()</code> 方法来访问。
 144             </para>
 145         </note>
 146
 147         <para>
 148             有三个特殊的变量可用于你的路由－'module'、 'controller' 和 'action'。这些特殊的变量被Zend_Controller_Dispatcher用来找出控制器和动作然后派遣过去。
 149         </para>
 150
 151         <note>
 152             <title>特殊变量</title>
 153             <para>
 154                 如果你选择通过 <code>setControllerKey</code> 和 <code>setActionKey</code>方法的方式来改变缺省值，这些特殊变量的名字可能会不同。
 155             </para>
 156         </note>
 157
 158     </sect2>
 159
 160     <sect2 id="zend.controller.router.default-routes">
 161         <title>缺省路由</title>
 162
 163         <para>
 164             Zend_Controller_Router_Rewrite 和缺省路由一起预先配置，它将以<code>controller/action</code>的形式匹配URIs。另外，模块名可以被指定作为第一个路径参数，允许这种<code>module/controller/action</code>形式的URIs。最后，它也将缺省地匹配任何另外的追加到URI的参数－<code>controller/action/var1/value1/var2/value2</code>。
 165         </para>
 166
 167         <para>
 168             一些路由如何匹配的例子：
 169         </para>
 170
 171         <programlisting role="php"><![CDATA[
 172 // Assuming the following:
 173 $ctrl->setControllerDirectory(
 174     array(
 175         'default' => '/path/to/default/controllers',
 176         'news'    => '/path/to/news/controllers',
 177         'blog'    => '/path/to/blog/controllers'
 178     )
 179 );
 180
 181 Module only:
 182 http://example/news
 183     module == news
 184
 185 Invalid module maps to controller name:
 186 http://example/foo
 187     controller == foo
 188
 189 Module + controller:
 190 http://example/blog/archive
 191     module     == blog
 192     controller == archive
 193
 194 Module + controller + action:
 195 http://example/blog/archive/list
 196     module     == blog
 197     controller == archive
 198     action     == list
 199
 200 Module + controller + action + params:
 201 http://example/blog/archive/list/sort/alpha/date/desc
 202     module     == blog
 203     controller == archive
 204     action     == list
 205     sort       == alpha
 206     date       == desc
 207 ]]>
 208         </programlisting>
 209
 210         <para>
 211             缺省路由是存储在RewriteRouter名（index）为'default'的简单的<code>Zend_Controller_Router_Route_Module</code>对象。它被创建多多少少象下面这样：
 212         </para>
 213
 214         <programlisting role="php"><![CDATA[
 215 $compat = new Zend_Controller_Router_Route_Module(array(),
 216                                                   $dispatcher,
 217                                                   $request);
 218 $this->addRoute('default', $compat);
 219 ]]>
 220         </programlisting>
 221
 222         <para>
 223             如果你不想这个特别的缺省路由在你的路由计划中，你可以重写你自己的‘缺省’路由（例如，把它存储在'default'名下）或用<code>removeDefaultRoutes()</code>完全清除它：
 224         </para>
 225
 226         <programlisting role="php"><![CDATA[
 227 // Remove any default routes
 228 $router->removeDefaultRoutes();
 229 ]]>
 230         </programlisting>
 231
 232     </sect2>
 233
 234     <sect2 id="zend.controller.router.rewritebase">
 235         <title>基本 URL 和子目录</title>
 236
 237         <para>
 238             rewrite路由器可以被用在子目录（例如，<code>http://domain.com/~user/application-root/</code>），在此例中，应用程序 (<code>/~user/application-root</code>)的基本URL应该能自动被<code>Zend_Controller_Request_Http</code>检测到并使用。
 239         </para>
 240
 241         <para>
 242             如果基本URL被误删除，你可以通过<code>Zend_Controller_Request_Http</code> 和调用 <code>setBaseUrl()</code> 方法（参见<xref linkend="zend.controller.request.http.baseurl" />）用你自己的基本路径重写它。
 243         </para>
 244
 245         <programlisting role="php"><![CDATA[
 246 $request->setBaseUrl('/~user/application-root/');
 247 ]]>
 248         </programlisting>
 249
 250     </sect2>
 251
 252     <sect2 id="zend.controller.router.routes">
 253         <title>Route Types</title>
 254         <xi:include href="Zend_Controller-Router-Route.xml" />
 255         <xi:include href="Zend_Controller-Router-Route-Static.xml" />
 256         <xi:include href="Zend_Controller-Router-Route-Regex.xml" />
 257     </sect2>
 258
 259     <sect2 id="zend.controller.router.add-config">
 260         <title>使用 Zend_Config with the RewriteRouter</title>
 261
 262         <para>
 263             有时候，用新路由更新配置文件比修改代码更方便。这个可能通过<code>addConfig()</code>方法来做。基本上，你创建一个Zend_Config-compatible配置，并在你的代码中读入然后传递给RewriteRouter。
 264         </para>
 265
 266         <para>
 267             作为例子，考虑下面的 INI 文件：
 268         </para>
 269
 270         <programlisting role="php"><![CDATA[
 271 [production]
 272 routes.archive.route = "archive/:year/*"
 273 routes.archive.defaults.controller = archive
 274 routes.archive.defaults.action = show
 275 routes.archive.defaults.year = 2000
 276 routes.archive.reqs.year = "\d+"
 277
 278 routes.news.type = "Zend_Controller_Router_Route_Static"
 279 routes.news.route = "news"
 280 routes.news.defaults.controller = "news"
 281 routes.news.defaults.action = "list"
 282
 283 routes.archive.type = "Zend_Controller_Router_Route_Regex"
 284 routes.archive.route = "archive/(\d+)"
 285 routes.archive.defaults.controller = "archive"
 286 routes.archive.defaults.action = "show"
 287 routes.archive.map.1 = "year"
 288 ; OR: routes.archive.map.year = 1
 289 ]]>
 290         </programlisting>
 291
 292         <para>
 293             上述的INI文件可以被读进<code>Zend_Config</code>对象：
 294         </para>
 295
 296         <programlisting role="php"><![CDATA[
 297 $config = new Zend_Config_Ini('/path/to/config.ini', 'production');
 298 $router = new Zend_Controller_Router_Rewrite();
 299 $router->addConfig($config, 'routes');
 300 ]]>
 301         </programlisting>
 302
 303         <para>
 304             在上面的例子中，我们告诉路由器去使用INI文件'routes'一节给它的路由。每个在这个节下的顶级键将用来定义路由名；上述例子定义了路由'archive'和'news'。每个路由接着要求，至少，一个'route'条目和一个或更多'defaults'条目；可选地，一个或更多'reqs'（'required'的简写）可能要求提供。总之，这些相对应的三个参数提供给<code>Zend_Controller_Router_Route_Interface</code>对象。一个选项键，'type'，可用来指定路由类的类型给特殊的路由；缺省地，它使用<code>Zend_Controller_Router_Route</code>。在上述例子中，'news'路由被定义来使用<code>Zend_Controller_Router_Route_Static</code>。
 305         </para>
 306     </sect2>
 307
 308     <sect2 id="zend.controller.router.subclassing">
 309         <title>Subclassing the Router</title>
 310
 311         <para>
 312             标准的rewrite路由器应当最大限度提供你所需的功能；大多时候，为了通过已知的路由提供新的或修改的功能，你将只需要创建一个新的路由类型
 313         </para>
 314
 315         <para>
 316             那就是说，你可能想要用不同的路由范例。接口<code>Zend_Controller_Router_Interface</code>提供了需要最少的信息来创建路由器，并包含一个单个的方法。
 317         </para>
 318
 319         <programlisting role="php"><![CDATA[
 320 interface Zend_Controller_Router_Interface
 321 {
 322   /**
 323    * @param  Zend_Controller_Request_Abstract $request
 324    * @throws Zend_Controller_Router_Exception
 325    * @return Zend_Controller_Request_Abstract
 326    */
 327   public function route(Zend_Controller_Request_Abstract $request);
 328 }
 329 ]]>
 330         </programlisting>
 331
 332         <para>
 333             路由只发生一次：当请求第一次接收到系统。路由器的意图是基于请求的环境决定控制器、动作和可选的参数，并把它们发给请求。请求对象接着传递给派遣器。如果不可能映射一个路由到一个派遣令牌，路由器对请求对象就什么也不做。
 334         </para>
 335     </sect2>
 336 </sect1>
 337 <!--
 338 vim:se ts=4 sw=4 et:
 339 -->