README

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

安装

使用composer安装

composer require nikic/fast-route

需要PHP 8.1或更高版本。

用法

以下是一个基本用法示例

<?php

require '/path/to/vendor/autoload.php';

$dispatcher = FastRoute\simpleDispatcher(function(FastRoute\ConfigureRoutes $r) {
    $r->addRoute('GET', '/users', 'get_all_users_handler');
    // {id} must be a number (\d+)
    $r->addRoute('GET', '/user/{id:\d+}', 'get_user_handler');
    // The /{title} suffix is optional
    $r->addRoute('GET', '/articles/{id:\d+}[/{title}]', 'get_article_handler');
});

// Fetch method and URI from somewhere
$httpMethod = $_SERVER['REQUEST_METHOD'];
$uri = $_SERVER['REQUEST_URI'];

// Strip query string (?foo=bar) and decode URI
if (false !== $pos = strpos($uri, '?')) {
    $uri = substr($uri, 0, $pos);
}
$uri = rawurldecode($uri);

$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\simpleDispatcher()函数来定义，该函数接受一个接受FastRoute\ConfigureRoutes实例的可调用函数。通过在收集器实例上调用addRoute()来添加路由。

$r->addRoute($method, $routePattern, $handler);

$method是一个大写HTTP方法字符串，用于指定应匹配的特定路由。可以使用数组指定多个有效方法。

// These two calls
$r->addRoute('GET', '/test', 'handler');
$r->addRoute('POST', '/test', 'handler');
// Are equivalent to this one call
$r->addRoute(['GET', 'POST'], '/test', 'handler');

默认情况下，$routePattern使用一种语法，其中{foo}指定一个名为foo的占位符，并匹配正则表达式[^/]+。要调整占位符匹配的模式，可以通过编写{bar:[0-9]+}指定一个自定义模式。以下是一些示例

// Matches /user/42, but not /user/xyz
$r->addRoute('GET', '/user/{id:\d+}', 'handler');

// Matches /user/foobar, but not /user/foo/bar
$r->addRoute('GET', '/user/{name}', 'handler');

// Matches /user/foo/bar as well
$r->addRoute('GET', '/user/{name:.+}', 'handler');

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

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

// This route
$r->addRoute('GET', '/user/{id:\d+}[/{name}]', 'handler');
// Is equivalent to these two routes
$r->addRoute('GET', '/user/{id:\d+}', 'handler');
$r->addRoute('GET', '/user/{id:\d+}/{name}', 'handler');

// Multiple nested optional parts are possible as well
$r->addRoute('GET', '/user[/{id:\d+}[/{name}]]', 'handler');

// This route is NOT valid, because optional parts can only occur at the end
$r->addRoute('GET', '/user[/{id:\d+}]/{name}', 'handler');

$handler参数不一定是回调，它也可以是控制器类名或任何其他您希望与路由关联的数据。FastRoute只会告诉您哪个处理程序对应于您的URI，您如何解释它取决于您。

常见请求方法的快捷方法

对于GET、POST、PUT、PATCH、DELETE和HEAD请求方法，提供了快捷方法。例如

$r->get('/get-route', 'get_handler');
$r->post('/post-route', 'post_handler');

等同于

$r->addRoute('GET', '/get-route', 'get_handler');
$r->addRoute('POST', '/post-route', 'post_handler');

路由组

此外，您还可以在组内指定路由。组内定义的所有路由将具有一个共同的前缀。

例如，将您的路由定义为

$r->addGroup('/admin', function (FastRoute\ConfigureRoutes $r) {
    $r->addRoute('GET', '/do-something', 'handler');
    $r->addRoute('GET', '/do-another-thing', 'handler');
    $r->addRoute('GET', '/do-something-else', 'handler');
});

将产生与以下相同的结果

$r->addRoute('GET', '/admin/do-something', 'handler');
$r->addRoute('GET', '/admin/do-another-thing', 'handler');
$r->addRoute('GET', '/admin/do-something-else', 'handler');

还支持嵌套组，在这种情况下，所有嵌套组的前缀都将结合。

缓存

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

<?php

$dispatcher = FastRoute\cachedDispatcher(function(FastRoute\ConfigureRoutes $r) {
    $r->addRoute('GET', '/user/{name}/{id:[0-9]+}', 'handler0');
    $r->addRoute('GET', '/user/{id:[0-9]+}', 'handler1');
    $r->addRoute('GET', '/user/{name}', 'handler2');
}, [
    'cacheKey' => __DIR__ . '/route.cache', /* required */
    // 'cacheFile' => __DIR__ . '/route.cache', /* will still work for v1 compatibility */
    'cacheDisabled' => IS_DEBUG_ENABLED,     /* optional, enabled by default */
    'cacheDriver' => FastRoute\Cache\FileCache::class, /* optional, class name or instance of the cache driver - defaults to file cache */
]);

函数的第二个参数是一个选项数组，可用于指定缓存键（例如，当使用文件进行缓存时的文件位置）、缓存驱动程序等。

分发URI

通过调用创建的分发器的dispatch()方法来分发URI。此方法接受HTTP方法和URI。获取这两个信息（并适当地规范化它们）是您的工作 - 此库不受PHP网络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/',
        ['id', '\d+'],
    ],
    [
        '/user/',
        ['id', '\d+'],
        '/',
        ['name', '[^/]+'],
    ],
]

然后将此数组传递给数据生成器的 addRoute() 方法。在添加所有路由之后，调用生成器的 getData()，它返回调度器所需的所有路由数据。这些数据格式未进一步指定 - 它与相应的调度器紧密耦合。

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

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

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

<?php

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

上面的选项数组对应默认值。通过将 MarkBased 替换为 GroupCountBased，可以切换到不同的调度策略。

关于 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 提供。