README

这个库提供了一个基于正则表达式的快速路由器实现。 博客文章解释了实现方式以及为什么它如此快速。

这是一个基于 nikic/FastRoute 的分支，增加了PHP 5.3兼容性修补程序。

用法

以下是一个基本用法示例

<?php

require '/path/to/FastRoute/src/bootstrap.php';

$dispatcher = FastRoute\simpleDispatcher(function(FastRoute\RouteCollector $r) {
    $r->addRoute('GET', '/user/{id:\d+}', 'handler1');
    $r->addRoute('GET', '/user/{id:\d+}/{name}', 'handler2');
    // Or alternatively
    $r->addRoute('GET', '/user/{id:\d+}[/{name}]', 'common_handler');
});

$routeInfo = $dispatcher->dispatch($httpMethod, $uri);
switch ($routeInfo[0]) {
    case FastRoute\Dispatcher::NOT_FOUND:
        // ... 404 Not Found
        break;
    case FastRoute\Dispatcher::METHOD_NOT_ALLOWED:
        $allowedMethods = $routeInfo[1];
        // ... 405 Method Not Allowed
        break;
    case FastRoute\Dispatcher::FOUND:
        $handler = $routeInfo[1];
        $vars = $routeInfo[2];
        // ... call $handler with $vars
        break;
}

定义路由

路由通过调用接受一个 FastRoute\RouteCollector 实例的 FastRoute\simpleDispatcher 函数来定义，路由通过在收集器实例上调用 addRoute() 来添加。

此方法接受必须匹配的路由HTTP方法、路由模式和关联的处理程序。处理程序不一定是回调（它也可以是控制器类名或您希望与路由关联的任何其他类型的数据）。

默认情况下，使用路由模式语法，其中 {foo} 指定一个名为 foo 的占位符，并匹配字符串 [^/]+。要调整占位符匹配的图案，可以通过编写 {bar:[0-9]+} 指定一个自定义模式。

此外，路由中用 [...] 包围的部分被认为是可选的，因此 /foo[bar] 将匹配 /foo 和 /foobar。可选部分仅支持在路由的末尾位置，不支持在路由中间位置。

路由占位符的自定义模式不得使用捕获组。例如，{lang:(en|de)} 不是一个有效的占位符，因为 () 是一个捕获组。相反，您可以使用 {lang:en|de} 或 {lang:(?:en|de)}。

之所以 simpleDispatcher 接受一个用于定义路由的回调，是为了允许无缝缓存。通过使用 cachedDispatcher 而不是 simpleDispatcher，您可以缓存生成的路由数据，并从缓存信息中构建分发器。

<?php

$dispatcher = FastRoute\cachedDispatcher(function(FastRoute\RouteCollector $r) {
    $r->addRoute('GET', '/user/{name}/{id:[0-9]+}', 'handler0');
    $r->addRoute('GET', '/user/{id:[0-9]+}', 'handler1');
    $r->addRoute('GET', '/user/{name}', 'handler2');
}, [
    'cacheFile' => __DIR__ . '/route.cache', /* required */
    'cacheDisabled' => IS_DEBUG_ENABLED,     /* optional, enabled by default */
]);

函数的第二个参数是一个选项数组，可以用来指定缓存文件位置等。

分发URI

通过调用创建的分发器的 dispatch() 方法来分发URI。此方法接受HTTP方法和URI。获取这两部分信息（并适当地规范化它们）是您的工作 - 此库不绑定到PHP Web SAPI。

dispatch() 方法返回一个数组，其第一个元素包含一个状态码。它是 Dispatcher::NOT_FOUND、Dispatcher::METHOD_NOT_ALLOWED 和 Dispatcher::FOUND 之一。对于不允许的方法状态，第二个数组元素包含允许用于提供的URI的HTTP方法列表。例如

[FastRoute\Dispatcher::METHOD_NOT_ALLOWED, ['GET', 'POST']]

注意：HTTP规范要求405“方法不允许”响应包含“Allow:”标题以详细说明请求资源的可用方法。使用FastRoute的应用程序应使用第二个数组元素在转接405响应时添加此标题。

对于找到的状态，第二个数组元素是与路由关联的处理程序，第三个数组元素是占位符名称到其值的字典。例如

/* Routing against GET /user/nikic/42 */

[FastRoute\Dispatcher::FOUND, 'handler0', ['name' => 'nikic', 'id' => '42']]

覆盖路由解析器和分发器

路由过程使用了三个组件：路由解析器、数据生成器和分发器。这三个组件遵循以下接口：

<?php

namespace FastRoute;

interface RouteParser {
    public function parse($route);
}

interface DataGenerator {
    public function addRoute($httpMethod, $routeData, $handler);
    public function getData();
}

interface Dispatcher {
    const NOT_FOUND = 0, FOUND = 1, METHOD_NOT_ALLOWED = 2;

    public function dispatch($httpMethod, $uri);
}

路由解析器接收一个路由模式字符串，并将其转换为路由信息数组，其中每个路由信息又是其部分的数组。这个结构最好通过例子来理解。

/* The route /user/{id:\d+}[/{name}] converts to the following array: */
[
    [
        '/user/',
        ['name', '[^/]+'],
    ],
    [
        '/user/',
        ['name', '[^/]+'],
        '/',
        ['id', '[0-9]+'],
    ],
]

然后可以将这个数组传递给数据生成器的 addRoute() 方法。在添加所有路由后，调用生成器的 getData() 方法，该方法返回分发器所需的所有路由数据。这些数据格式未做进一步说明——它与相应的分发器紧密耦合。

分发器通过构造函数接受路由数据，并提供一个您已经熟悉的 dispatch() 方法。

路由解析器可以单独重写（以使用不同的模式语法），但是数据生成器和分发器应该始终成对更改，因为前者的输出与后者的输入紧密耦合。生成器和分发器分离的原因是，只有后者在使用缓存时才需要（因为前者的输出是缓存的内容。）

当使用上面的 simpleDispatcher / cachedDispatcher 函数时，重写通过选项数组进行。

<?php

$dispatcher = FastRoute\simpleDispatcher(function(FastRoute\RouteCollector $r) {
    /* ... */
}, [
    'routeParser' => 'FastRoute\\RouteParser\\Std',
    'dataGenerator' => 'FastRoute\\DataGenerator\\GroupCountBased',
    'dispatcher' => 'FastRoute\\Dispatcher\\GroupCountBased',
]);

上述选项数组对应默认值。通过将 GroupCountBased 替换为 GroupPosBased，可以切换到不同的分发策略。

关于 HEAD 请求的说明

HTTP 规范要求服务器支持 GET 和 HEAD 方法

所有通用服务器都必须支持 GET 和 HEAD 方法

为了避免强制用户手动为每个资源注册 HEAD 路由，我们回退到匹配给定资源的可用 GET 路由。PHP 网络SAPI会透明地从 HEAD 响应中删除实体主体，因此这种行为对绝大多数用户没有影响。

然而，在 Web SAPI 环境之外（例如，自定义服务器）使用 FastRoute 的实现者必须不发送对 HEAD 请求生成的实体主体。如果您是非 SAPI 用户，这是您的责任；FastRoute 没有权限阻止您在这种情况下破坏 HTTP。

最后，请注意，应用程序可以为给定资源指定自己的 HEAD 方法路由，以完全绕过这种行为。

致谢

这个库基于 Levi Morrison 为 Aerys 服务器实现的路由器。

大量的测试以及 HTTP 兼容性考虑由 Daniel Lowrey 提供。