路由¶

路由的配置¶

应用程序中的路由是在 app/Config/routes.php 中配置的。当处理路由被 Dispatcher 引入，让你可以定义应用程序要使用的特定路由。在该文件中声 明的路由从上而下处理，直到收到的请求匹配。这意味着放置路由的顺序会影响路由的解析。 通常好的做法是，把最常访问的路由尽可能放在路由文件的最上面。这可以省去对每个请求 不得不检查若干个不能匹配的路由。

路由以它们连入的顺序来解析和匹配。如果你定义两个类似的路由，定义的第一个路由比后 定义的那个有更高的优先级。在连接路由之后，你可以使用 Router::promote() 来操纵路由的顺序。

CakePHP 也带有一些默认的路由帮你开始。以后如果你肯定不需要它们了，可以把它们关闭。 欲知如何关闭默认的路由，请参见 关闭默认路由。

默认的路由¶

在了解如何配置自己的路由之前，你应当知道 CakePHP 带有一组默认的路由。CakePHP 的 默认路由适用于任何应用程序的很多情况。把一个动作的名称放入请求中，就可以直接从网 址访问该动作。也可以用网址传递参数到控制器动作。

// 网址（*URL*）模式的默认路由：
http://example.com/controller/action/param1/param2/param3

网址 /posts/view 映射到 PostsController 的 view() 动作，而网址 /products/view_clearance 映射到 ProductsController 的 view_clearance() 动作。

默认的路由设置也让你可以用网址传递参数到动作。例如，对 /posts/view/25 的请求等于 调用 PostsController 的 view(25)。默认的路由也提供插件的路由、前缀路由，如果你选 择使用这些功能的话。

内置的路由位于 Cake/Config/routes.php。你可以通过在应用程序的 routes.php 文件中去掉默认路由来关闭它们。

连接路由¶

定义你自己的路由让你可以定义应用程序如何对一个给定的网址作出反应。用 Router::connect() 方法在 app/Config/routes.php 文件中定义定义自 己的路由。

connect() 方法接受最多三个参数：希望匹配的网址、路由元素的默认值、和帮助路由 匹配网址中的元素的正则表达式规则。

路由定义的基本格式为:

Router::connect(
    'URL',
    array('default' => 'defaultValue'),
    array('option' => 'matchingRegex')
);

第一个参数用来告诉路由器你要控制哪种网址。网址是斜线分隔的普通字符串，但也可以包 含通配符(*)或者 路由元素。使用通配符告诉路由器，你愿意接受任何提供 的额外参数。不含*的路由只匹配提供的模板模式。

一旦指定了网址，用 connect() 的最后两个参数来告诉 CakePHP，一旦一个请求匹配 了，要如何处理它。第二个参数是一个关联数组。数组的键应当以网址中的路由元素来命名， 或者是默认元素： :controller 、 :action 和 :plugin。数组中的值是这些 键的缺省值。让我们看一些基本的例子，再来看如何使用 connect() 的第三个参数:

Router::connect(
    '/pages/*',
    array('controller' => 'pages', 'action' => 'display')
);

以上这个路由在随 CakePHP 发布的 routes.php 文件中。该路由匹配任何以 /pages/ 开始的网址，并把它交给 PagesController(); 的 display() 动作。请求 /pages/products 会映射到 PagesController->display('products')。

除了贪婪的星号 /*，还有 /** 后缀星号语法。使用后缀双星号，会捕获网址的其 余部分为一个传入参数。当你要使用含有 / 的参数时就有用了:

Router::connect(
    '/pages/**',
    array('controller' => 'pages', 'action' => 'show')
);

传入的网址 /pages/the-example-/-and-proof 会导致单个传入参数 the-example-/-and-proof。

你可以使用 Router::connect() 的第二个参数来提供任何由路由的默认值组 成的路由参数:

Router::connect(
    '/government',
    array('controller' => 'pages', 'action' => 'display', 5)
);

这个例子说明如何使用 connect() 方法的第二个参数来定义默认参数。如果你构建一 个网站，有针对不同类别客户的产品，你也许会考虑创建一个路由。这让你可以链接 /government，而不是 /pages/display/5。

另一个路由器的常见用法是为控制器定义”别名”。比方说，我们不要访问通常的网址 /users/some_action/5，希望能够通过 /cooks/some_action/5 来访问。下面的路 由轻易地实现了:

Router::connect(
    '/cooks/:action/*', array('controller' => 'users')
);

这就是告诉路由器，任何以 /cooks/ 开始的网址应当交给用户控制器。调用的动作取 决于 :action 参数的值。使用 路由元素，就能够创造路由变量，接受 用户输入或者变量。上面的路由也使用了贪婪的星号。贪婪的星号告诉 Router，这个路由应当接受任何给定的额外位置参数。这些参数会被放入 传入参数 数组供访问。

当生成网址时，也使用路由。如果上述路由最先匹配，使用 array('controller' => 'users', 'action' => 'some_action', 5) 作为网址，就会 输出 /cooks/some_action/5。

默认情况下，所有命名(named)和传入(passed)参数会从匹配贪婪模板的网址中提取。 不过，如果需要，可以使用 Router::connectNamed() 来配置哪个命名参数如 何解析。

Router::connect(
    '/:controller/:id',
    array('action' => 'view'),
    array('id' => '[0-9]+')
);

Router::connect('/:action', array('controller' => 'home'));

Router::connect(
    '/:userShortcut',
    array('controller' => 'teachers', 'action' => 'profile', 1),
    array('userShortcut' => '(?i:principal)')
);

Router::connect(
    '/:controller/:year/:month/:day',
    array('action' => 'index'),
    array(
        'year' => '[12][0-9]{3}',
        'month' => '0[1-9]|1[012]',
        'day' => '0[1-9]|[12][0-9]|3[01]'
    )
);

// SomeController.php
public function view($articleId = null, $slug = null) {
    // 这里是一些代码...
}

// routes.php
Router::connect(
    '/blog/:id-:slug', // 例如 /blog/3-CakePHP_Rocks
    array('controller' => 'blog', 'action' => 'view'),
    array(
        // 顺序有关，因为这会简单地把 ":id" 映射到动作中的 $articleId 参数
        'pass' => array('id', 'slug'),
        'id' => '[0-9]+'
    )
);

// view.ctp
// 这会返回链接 /blog/3-CakePHP_Rocks
echo $this->Html->link('CakePHP Rocks', array(
    'controller' => 'blog',
    'action' => 'view',
    'id' => 3,
    'slug' => 'CakePHP_Rocks'
));

Router::connect(
    '/:controller/:action/*',
    array(),
    array(
        'named' => array(
            'wibble',
            'fish' => array('action' => 'index'),
            'fizz' => array('controller' => array('comments', 'other')),
            'buzz' => 'val-[\d]+'
        )
    )
);

Configure::write('Routing.prefixes', array('admin'));

Router::connect(
    '/admin',
    array('controller' => 'pages', 'action' => 'index', 'admin' => true)
);

Configure::write('Routing.prefixes', array('admin', 'manager'));

Router::connect(
    "/{$prefix}/:plugin/:controller",
    array('action' => 'index', 'prefix' => $prefix, $prefix => true)
);
Router::connect(
    "/{$prefix}/:plugin/:controller/:action/*",
    array('prefix' => $prefix, $prefix => true)
);
Router::connect(
    "/{$prefix}/:controller",
    array('action' => 'index', 'prefix' => $prefix, $prefix => true)
);
Router::connect(
    "/{$prefix}/:controller/:action/*",
    array('prefix' => $prefix, $prefix => true)
);

// 进入前缀路由。
echo $this->Html->link(
    'Manage posts',
    array('manager' => true, 'controller' => 'posts', 'action' => 'add')
);

// 离开前缀
echo $this->Html->link(
    'View Post',
    array('manager' => false, 'controller' => 'posts', 'action' => 'view', 5)
);

echo $this->Html->link(
    'New todo',
    array('plugin' => 'todo', 'controller' => 'todo_items', 'action' => 'create')
);

echo $this->Html->link(
    'New todo',
    array('plugin' => null, 'controller' => 'users', 'action' => 'profile')
);

Router::parseExtensions('html', 'rss');

Router::connect(
    '/page/:title',
    array('controller' => 'pages', 'action' => 'view'),
    array(
        'pass' => array('title')
    )
);

$this->Html->link(
    'Link title',
    array(
        'controller' => 'pages',
        'action' => 'view',
        'title' => 'super-article',
        'ext' => 'html'
    )
);

Router::connect(
    "/:controller/:id",
    array("action" => "edit", "[method]" => "PUT"),
    array("id" => "[0-9]+")
);

传入参数¶

传入参数(passed argument)是发起请求时使用的其它参数或路径片段。它们经常用来给 控制器方法传递参数。

http://localhost/calendars/view/recent/mark

在上面的例子中，recent 和 mark 都是 CalendarsController::view() 的参 数。传入参数以三种方式提供给控制器。首先可以作为被调用动作方法的参数，其次可以在 $this->request->params['pass'] 中作为数字索引的数组访问。最后，可以在 $this->passedArgs 中通过和第二种同样的方式访问。在使用自定义路由时，你也可以 强制特定的参数作为传入参数。

如果你访问上面提到的网址，控制器动作如下:

CalendarsController extends AppController {
    public function view($arg1, $arg2) {
        debug(func_get_args());
    }
}

你就会得到如下输出:

Array
(
    [0] => recent
    [1] => mark
)

同样的数据也可以在控制器、视图和助件中通过 $this->request->params['pass'] 和 $this->passedArgs 得到。在 pass 数组中的值以它们在调用的网址中出现的顺序作为 数字索引:

debug($this->request->params['pass']);
debug($this->passedArgs);

上面的任何一个都会输出:

Array
(
    [0] => recent
    [1] => mark
)

在生成网址时，使用 routing array，你可以添加不带字符串索引的值作为传入参 数:

array('controller' => 'posts', 'action' => 'view', 5)

因为 5 有数字键，所以它会被当作传入参数。

命名参数¶

你可以给参数命名并用网址传递它们的值。对 /posts/view/title:first/category:general 的请求会导致对 PostsController 控制 器的 view() 动作的调用。在这个动作中，你可以在 $this->params['named'] 中得到 title 和 category 参数的值。它们也可以在 $this->passedArgs 中得到。在这两种 情况中，都可以用它们的名称作为索引来访问。如果省略了命名参数，它们就不会(在这两 个数组中)被设置。

一些默认路由的总结性例子也许有用:

使用默认路由从网址到控制器动作的映射：

网址： URL: /monkeys/jump
映射： Mapping: MonkeysController->jump();

网址： URL: /products
映射： Mapping: ProductsController->index();

网址： URL: /tasks/view/45
映射： Mapping: TasksController->view(45);

网址： URL: /donations/view/recent/2001
映射： Mapping: DonationsController->view('recent', '2001');

网址： URL: /contents/view/chapter:models/section:associations
映射： Mapping: ContentsController->view();
$this->passedArgs['chapter'] = 'models';
$this->passedArgs['section'] = 'associations';
$this->params['named']['chapter'] = 'models';
$this->params['named']['section'] = 'associations';

当制定自定义路由时，一个常见错误是，使用命名参数会破坏你的自定义路由。为了解决这 个问题，你应当告诉路由器哪个参数要作为命名参数。不知道这个，路由器就无法决定命名 的参数实际上是要作为命名参数还是路由参数，而会默认认为你要它们作为路由参数。要在 路由器中使用命名参数，请使用 Router::connectNamed() 方法:

Router::connectNamed(array('chapter', 'section'));

这会确保反向路由正确地处理你的 chapter 和 section 参数。

当生成网址时，使用 routing array 就可以把和名称匹配的字符串键及其值添加 为命名参数:

array('controller' => 'posts', 'action' => 'view', 'chapter' => 'association')

因为 ‘chapter’ 不匹配任何定义的路由元素，它就会被认为是命名参数。

命名参数也支持使用数组来生成和解析网址。语法和 GET 参数的数组语法非常类似。当生 成网址时可以使用以下语法:

$url = Router::url(array(
    'controller' => 'posts',
    'action' => 'index',
    'filter' => array(
        'published' => 1,
        'frontpage' => 1
    )
));

以上代码会生成网址 /posts/index/filter[published]:1/filter[frontpage]:1。然 后参数会被解析，并作为数组存储在控制器的 passedArgs 变量中，就象你把它们发送给 Router::url 一样:

$this->passedArgs['filter'] = array(
    'published' => 1,
    'frontpage' => 1
);

数组也可以深度嵌套，让你在传递参数时有更多的灵活性:

$url = Router::url(array(
    'controller' => 'posts',
    'action' => 'search',
    'models' => array(
        'post' => array(
            'order' => 'asc',
            'filter' => array(
                'published' => 1
            )
        ),
        'comment' => array(
            'order' => 'desc',
            'filter' => array(
                'spam' => 0
            )
        ),
    ),
    'users' => array(1, 2, 3)
));

你就会得到象这样相当长的网址(折行是为了便于阅读):

posts/search
  /models[post][order]:asc/models[post][filter][published]:1
  /models[comment][order]:desc/models[comment][filter][spam]:0
  /users[]:1/users[]:2/users[]:3

得到的要传递给控制器的数组，和传递给路由器的是一致的:

$this->passedArgs['models'] = array(
    'post' => array(
        'order' => 'asc',
        'filter' => array(
            'published' => 1
        )
    ),
    'comment' => array(
        'order' => 'desc',
        'filter' => array(
            'spam' => 0
        )
    ),
);

Router::connectNamed(false);

Router::connectNamed(false, array('default' => true));

Router::connectNamed(
    array('page' => '[\d]+'),
    array('default' => false, 'greedy' => false)
);

Router::connectNamed(
    array('page'),
    array('default' => false, 'greedy' => false)
);

Router::connectNamed(
    array('page' => array('action' => 'index')),
    array('default' => false, 'greedy' => false)
);

Router::connectNamed(
    array('page' => array('action' => 'index', 'controller' => 'pages')),
    array('default' => false, 'greedy' => false)
);

反向路由¶

反向路由是 CakePHP 中的特性，用来让你容易地改变网址结构，而不必改动所有代码。使 用 路由数组 来定义网址，以后你就可以配置路由，而生成的网 址就会自动更新。

如果象下面这样用字符串创建网址:

$this->Html->link('View', '/posts/view/' . $id);

而后来决定 /posts 实际上应该叫做 ‘articles’，你就不得不查看整个应用程序的代 码，替换网址。然而，如果象下面这样定义链接:

$this->Html->link(
    'View',
    array('controller' => 'posts', 'action' => 'view', $id)
);

那么当你决定改变网址时，你可以只定义一个路由就达到目的。这不但会改变接收网址的映 射，也改变了生成的网址。

在使用数组网址时，你可以使用特殊的键来定义查询字符串(query string)参数和文档片 段(document fragment):

Router::url(array(
    'controller' => 'posts',
    'action' => 'index',
    '?' => array('page' => 1),
    '#' => 'top'
));

// 会生成类似这样的网址
/posts/index?page=1#top

重定向路由¶

重定向路由让你可以对收到的路由发送 HTTP 状态 30x 重定向，把它们指向不同的网址。 这可以用于当你想要通知客户端应用程序，一个资源被移动了，而你又不想为同一内容分配 两个网址。

重定向路由不同于普通路由，因为如果遇到匹配的网址，实际上会执行文件头重定向。重定 向可以指向应用程序内的目标，也可以指向外部的地址:

Router::redirect(
    '/home/*',
    array('controller' => 'posts', 'action' => 'view'),
    // 或者对视图动作等待 $id 作为参数的默认路由，使用
    // array('persist'=>array('id'))
    array('persist' => true)
);

重定向 /home/* 到 /posts/view，并传递参数到 /posts/view。使用数组作 为重定向目标让你可以使用其它路由来定义字符串网址应该重定向到哪里。你可以使用字符 串网址作为目标重定向到外部地址:

Router::redirect('/posts/*', 'https://google.com', array('status' => 302));

这会以 HTTP 状态 302 重定向 /posts/* 到 https://google.com。

关闭默认路由¶

如果你完全自定义了全部路由，并想要避免任何可能来自搜索引擎的重复内容惩罚，你可以 从应用程序的 routes.php 文件删除 CakePHP 提供的默认路由来去掉它们。

当用户试图访问通常由 CakePHP 提供但没有显式连接的网址，就会引起 CakePHP 报错。

自定义路由类¶

自定义路由类让你可以扩展并改变单个路由如何解析请求和处理反向路由。自定义路由应当 在 app/Routing/Route 目录中创建，而且应当扩展 CakeRoute 并实现 match() 和 parse() 两个方法中的一个或全部。parse() 方法用于解析请求， 而 match() 方法用于处理反向路由。

要使用自定义路由，你可以在指定路由时使用 routeClass 选项，并且在使用它之前加 载包含路由(类)的文件:

App::uses('SlugRoute', 'Routing/Route');

Router::connect(
     '/:slug',
     array('controller' => 'posts', 'action' => 'view'),
     array('routeClass' => 'SlugRoute')
);

这个路由会创建一个 SlugRoute 类的实例，让你可以实现自定义参数处理。

路由 API¶

class Router¶

路由器管理发出网址的生成、解析接收的请求网址为 CakePHP 可以调配的参数集。

static Router::connect($route, $defaults = array(), $options = array())¶

参数

• $route (string) – 描述路由模板的字符串。

• $defaults (array) – 描述默认路由参数的数组。这些参数默认会被使用，可以被 提供非动态的路由参数。

• $options (array) – 路由中命名元素和对应的元素应当匹配的正则表达式构成的 数组。也包含额外的参数，比如哪个路由参数应当移入传入参数，提供路由参数的 模式，以及提供自定义路由类的名称。

路由是一种连接请求网址和应用程序中的对象的方法。在其核心，路由是用于匹配请求 到目的地的一组正则表达式。

例如:

Router::connect('/:controller/:action/*');

第一个参数被当作控制器名称，而第二个参数被当作当作名称。’/*’ 语法使该路由贪 婪，这样它就会匹配象 /posts/index 以及象 /posts/edit/1/foo/bar 这样的 请求。

Router::connect(
    '/home-page',
    array('controller' => 'pages', 'action' => 'display', 'home')
);

上面这个说明路由参数默认值的用法。而为静态路由提供路由参数。

Router::connect(
    '/:lang/:controller/:action/:id',
    array(),
    array('id' => '[0-9]+', 'lang' => '[a-z]{3}')
);

说明连接路由和自定义路由参数，以及为这些参数提供模式。路由参数的模式不需要捕 获分组(capturing group)，因为每个路由参数都会(自动)添加一个(捕获分组)。

$options 参数提供了三个’特殊的’键。pass 、 persist 和 routeClass 在 $options 数组中有特殊的含义。

• pass 用于定义那个路由参数应当移入 pass 数组。添加参数到 pass 数组会把 它从正常的路由数组中删除。例如 'pass' => array('slug')。

• persist 用于定义在生成新网址时哪个路由参数应当自动包括在内。你可以覆盖 持久参数，只需在网址中重新定义它们，或者通过设置该参数为 false。例如 'persist' => array('lang')。

• routeClass 用于通过自定义路由类来扩展和改变单个路由如何解析请求及处理 反向路由。例如 'routeClass' => 'SlugRoute'。

• named 用于在路由级别配置命名参数。该键使用与 Router::connectNamed() 相同的键。

static Router::redirect($route, $url, $options = array())¶

参数

• $route (string) – 路由模板，决定哪些网址要重定向。

• $url (mixed) – 重定向目的地，或者是 routing array 或者是字符串网 址。

• $options (array) – 重定向选项数组。

连接路由器中新的重定向路由。欲知详情，请参见 重定向路由。

static Router::connectNamed($named, $options = array())¶

参数

• $named (array) – 命名参数列表。接受键值对，值为要匹配的正则表达式字符串、 或者数组。

• $options (array) – 可以控制所有设置： separator、greedy、reset、default。

指定 CakePHP 应当从接收的网址中解析哪些命名参数。默认情况下，CakePHP 会从收 到的网址中解析所有命名参数。欲知详情，请参见 控制命名参数。

static Router::promote($which = null)¶

参数

• $which (integer) – 从零开始的数组索引，代表要移动的路由。例如，如果添加 了 3 个路由，最后一个路由就是 2。

把一个路由(默认情况下，是最后一个添加的)提前到列表的最开始。

static Router::url($url = null, $full = false)¶

参数

• $url (mixed) – CakePHP 的相对网址，比如 “/products/edit/92” 或者 “/presidents/elect/4” 或者 routing array

• $full (mixed) – 如果是 (boolean) true，完整的基准目录网址会加在结果前面。 如果是数组，则接受如下的键

• escape — 用于当生成嵌入 HTML 的网址时，转义查询字符串’&’

• full — 如果为 true，完整的基准目录网址会加在前面。

生成指定动作的网址。返回网址指向控制器和动作组合的网址。$url 可以是：

• Empty — 该方法会寻找真正的控制器/动作的地址。

• ‘/’ — 该方法会寻找应用程序的基准网址。

• 控制器/动作的组合 — 该方法会寻找其对应的网址。

有一些’特殊’的参数会改变最终生成的网址字符串：

• base — 设置为 false 来去掉生成的网址中的基准路径。如果你的应用程序不在 根目录，这可以用来生成’CakePHP 的相对’网址。CakePHP 的相对网址在使用 requestAction 是必须的。

• ? — 接受查询字符串参数数组

• # — 让你可以设置网址哈希片段(hash fragment)。

• full_base — 如果是 true，Router::fullBaseUrl() 的值会附加 在生成的网址的前面。

static Router::mapResources($controller, $options = array())¶

创建给定控制器的 REST 资源路由。欲知详情，请参见 REST 一 节。

static Router::parseExtensions($types)¶

用在 routes.php 文件中来声明应用程序支持哪个 文件扩展名。不提供 参数，则支持所有的文件扩展名。

static Router::setExtensions($extensions, $merge = true)¶

2.2 新版功能.

设置或添加合法的扩展名。要解析扩展名，你仍然必须调用 Router::parseExtensions() 方法。

static Router::defaultRouteClass($classname)¶

2.1 新版功能.

设置将来连接路由时使用的默认路由。

static Router::fullBaseUrl($url = null)¶

2.4 新版功能.

获得或设置生成网址时使用的基准网址(baseURL)。设置该值时，应当确保引入包括 协议的完全合格域名(fully qualified domain name)。

用该方法设置值，也会更新 Configure 中的 App.fullBaseUrl。

class CakeRoute¶

自定义路由基于的基类。

CakeRoute::parse($url)¶

参数

• $url (string) – 要解析的字符串网址。

解析收到的网址，并生成请求参数数组，供调度器(dispatcher)处理。扩展这个方法 让你可以定制如何把收到的网址转换成数组。从网址返回 false 来表示不匹配。

CakeRoute::match($url)¶

参数

• $url (array) – 要转换成字符串网址的路由数组。

试图匹配网址数组。如果网址匹配路由参数和设置，就返回生成的字符串网址。如果网 址不匹配路由参数，返回 false。该方法处理网址数组的反向路由或转换为字符串网址。

CakeRoute::compile()¶

强制路由编译它的正则表达式。