README

致谢

此库是 nikic/FastRoute 实现的修改版。

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

安装

使用composer安装

composer require pedrofaria/router

需要PHP 5.4或更高版本。

用法

以下是一个基本用法示例

<?php

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

$dispatcher = Router\simpleDispatcher(function(Router\RouteCollector $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');
    // Pass extra data for check ahead.
    $r->addRoute('DELETE', '/user/{id:\d+}', ['auth']);
});

// 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);

try {
    $routeInfo = $dispatcher->dispatch($httpMethod, $uri);

    $handler = $routeInfo->handler;
    $vars = $routeInfo->variables;

    if (in_array('auth', $routeInfo->data)) {
        // Check if current user is authenticated before continue
    }
    
    // ... call $handler with $vars
} catch (\Router\Exception\HttpNotFoundException $e) {
    // ... 404 Not Found
} catch (\Router\Exception\HttpMethodNotAllowedException $e) {
    // ... 405 Method Not Allowed
}

定义路由

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

$r->addRoute($method, $routePattern, $handler, $data = []);

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

$data 数组参数是可选的，您可以使用它来设置在调用 $handler 之前或之后使用的信息。

常见请求方法的快捷方法

对于 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 (RouteCollector $r) {
    $r->addRoute('GET', '/do-something', 'handler');
    $r->addRoute('GET', '/do-another-thing', 'handler', ['other-data']);
    $r->addRoute('GET', '/do-something-else', 'handler');
}, ['extra_data']);

将产生与以下相同的结果

$r->addRoute('GET', '/admin/do-something', 'handler', ['extra_data']);
$r->addRoute('GET', '/admin/do-another-thing', 'handler', ['extra_data', 'other-data']);
$r->addRoute('GET', '/admin/do-something-else', 'handler', ['extra_data']);

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

缓存

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

<?php

$dispatcher = Router\cachedDispatcher(function(Router\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 SAPIs无关。

方法 dispatch() 返回一个对象（请参阅下方的对象结构）。如果找不到路由或HTTP方法不允许，方法 dispatch() 将抛出异常。抛出 Router\Exception\HttpNotFoundException 或 Router\Exception\HttpMethodNotAllowedException 异常。对于不允许的方法异常，您可以使用方法 getAllowedMethod() 获取为提供的URI允许的HTTP方法列表。

//...
catch (Router\Exception\HttpMethodNotAllowedException $e) {
    $allowedMethods = $e->getAllowedMethod();
}

注意：HTTP规范要求405 Method Not Allowed响应包含Allow:头以详细说明请求资源的可用方法。使用Router的应用程序应在传递405响应时使用第二个数组元素添加此头。

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

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

object(Router\Route)#7 (5) {
  ["httpMethod"]=>
  string(3) "GET"
  ["regex"]=>
  string(21) "/user/([^/]+)/([^/]+)"
  ["variables"]=>
  array(2) {
    ["name"]=>
    string(5) "nikic"
    ["id"]=>
    string(2) "42"
  }
  ["handler"]=>
  string(8) "handler0"
  ["data"]=>
  array(0) {
  }
}

重写路由解析器和分发器

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

<?php

namespace Router;

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

interface DataGenerator {
    public function addRoute($httpMethod, $routeData, $handler, array $data = []);
    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 = Router\simpleDispatcher(function(Router\RouteCollector $r) {
    /* ... */
}, [
    'routeParser' => 'Router\\RouteParser\\Std',
    'dataGenerator' => 'Router\\DataGenerator\\GroupCountBased',
    'dispatcher' => 'Router\\Dispatcher\\GroupCountBased',
]);

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

关于HEAD请求的说明

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

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

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

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

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

致谢

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

大量测试以及HTTP合规性考虑由Daniel Lowrey提供。