README

HTTP 请求路由器

这个库提供了基于正则表达式的快速路由器实现。有关实现方式和为什么它更快的信息，请参阅这篇文章。

安装

通过 Composer 安装

composer require triangle/router

需要 PHP 8.0 或更高版本。

用法

使用示例

<?php

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

$dispatcher = simpleRouteDispatcher(function(Triangle\Router\RouteCollector $r) {
    $r->addRoute('GET', '/users', 'get_all_users_handler');
    // {id} должен быть числом (\d+)
    $r->addRoute('GET', '/user/{id:\d+}', 'get_user_handler');
    // Суффикс /{title} не обязателен
    $r->addRoute('GET', '/articles/{id:\d+}[/{title}]', 'get_article_handler');
});

// Получаем метод и URI откуда нужно
$httpMethod = $_SERVER['REQUEST_METHOD'];
$uri = $_SERVER['REQUEST_URI'];

// Удалим строку запроса (?foo=bar) и декодируем URI
if (false !== $pos = strpos($uri, '?')) {
    $uri = substr($uri, 0, $pos);
}
$uri = rawurldecode($uri);

$routeInfo = $dispatcher->dispatch($httpMethod, $uri);
switch ($routeInfo[0]) {
    case Triangle\Router\Dispatcher::NOT_FOUND:
        // ... 404 Ничего не найдено
        break;
    case Triangle\Router\Dispatcher::METHOD_NOT_ALLOWED:
        $allowedMethods = $routeInfo[1];
        // ... 405 Метод не поддерживается
        break;
    case Triangle\Router\Dispatcher::FOUND:
        $callback = $routeInfo[1];
        $vars = $routeInfo[2];
        // ... Здесь можно вызвать, например $callback($vars)
        break;
}

定义路由

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

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

$method 参数是用于匹配特定路由的 HTTP 方法的大写字符串。可以通过数组指定多个允许的方法。

// 2 маршрута:
$r->addRoute('GET', '/test', 'handler');
$r->addRoute('POST', '/test', 'handler');
// Эквивалентны записи:
$r->addRoute(['GET', 'POST'], '/test', 'handler');

默认情况下，$routePattern 使用以下语法：其中 {foo} 指定名为 foo 的占位符，并对应正则表达式 [^/]+。要设置占位符对应的模板，可以指定用户模板，例如 {bar:[0-9]+}。以下是一些示例：

// Маршрут /user/42 совпадёт, но /user/xyz - уже нет
$r->addRoute('GET', '/user/{id:\d+}', 'handler');

// Маршрут /user/foobar совпадёт, но /user/foo/bar  - уже нет
$r->addRoute('GET', '/user/{name}', 'handler');

// Маршрут /user/foo/bar совпадёт
$r->addRoute('GET', '/user/{name:.+}', 'handler');

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

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

// Этот маршрут
$r->addRoute('GET', '/user/{id:\d+}[/{name}]', 'handler');
// Эквивалентен двум следующим
$r->addRoute('GET', '/user/{id:\d+}', 'handler');
$r->addRoute('GET', '/user/{id:\d+}/{name}', 'handler');

// Также возможны множественные вложенные необязательные части
$r->addRoute('GET', '/user[/{id:\d+}[/{name}]]', 'handler');

// Этот маршрут НЕ действителен, поскольку необязательные части могут встречаться только в конце
$r->addRoute('GET', '/user[/{id:\d+}]/{name}', 'handler');

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

常用方法的缩写

对于 GET、POST、PUT、PATCH、DELETE、HEAD 和 OPTIONS 方法，提供了缩写。例如，以下路由等效：

$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->any('/any-route', 'any_handler');

路由分组

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

例如，将您的路由定义如下：

$r->addGroup('/admin', function (RouteCollector $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');

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

缓存

simpleRouteDispatcher 接受回调函数以定义路由的原因是允许无缝缓存。通过使用 cachedRouteDispatcher 代替 simpleRouteDispatcher，您可以缓存生成的路由数据并从缓存信息创建一个处理器。

<?php

$dispatcher = cachedRouteDispatcher(function(Triangle\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', /* обязательно */
    'cacheDisabled' => IS_DEBUG_ENABLED,     /* необязательно, включено по умолчанию */
]);

函数的第二个参数是参数数组，您可以使用它指定缓存文件的位置等。

URI 处理

通过调用创建的处理器上的 dispatch() 方法来处理 URI。此方法接受 HTTP 方法和 URI。获取这两个信息位（以及它们的规范化）是您的工作 — 这个库不依赖于 PHP SAPI。

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

[Triangle\Router\Dispatcher::METHOD_NOT_ALLOWED, ['GET', 'POST']]

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

对于 Dispatcher::FOUND 状态，数组的第二个元素是与路由关联的处理程序，第三个元素是变量名称到其值的映射字典。例如

/* Маршрутизация по GET /user/localzet/42 */

[Triangle\Router\Dispatcher::FOUND, 'handler0', ['name' => 'localzet', 'id' => '42']]

重定义路由解析器和调度器

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

<?php

namespace Triangle\Router;

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

路由解析器接受路由模板字符串并将其转换为包含路由信息的数组，其中每个信息本身又是其各部分的数组。最好通过以下示例来理解这种结构

/* Маршрут /user/{id:\d+}[/{name}] преобразуется в следующий массив: */
[
    [
        '/user/',
        ['id', '\d+'],
    ],
    [
        '/user/',
        ['id', '\d+'],
        '/',
        ['name', '[^/]+'],
    ],
]

然后可以将此数组传递给数据生成器的 addRoute() 方法。添加所有路由后，调用数据生成器的 getData() 方法，该方法返回调度器所需的所有路由数据。这些数据的格式在此未指定——它与相应的调度器密切相关。

调度器通过构造函数接收路由数据，并提供了您已熟悉的 dispatch() 方法。

可以单独重定义路由解析器（以使用不同的模板语法），但数据生成器和调度器始终应作为一对进行更改，因为第一个的输出与第二个的输入紧密相关。将生成器和调度器分开的原因是，只有在缓存时才需要最后一个（因为第一个的输出是缓存的内容）。

当使用上面提到的 simpleRouteDispatcher / cachedRouteDispatcher 函数时，重定义通过参数数组进行

<?php

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

上面的参数数组对应于默认值。将 GroupCountBased 替换为 GroupPosBased，您可以切换到另一种调度策略。

关于 HEAD 请求的说明

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

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

为了防止用户必须手动为每个资源注册 HEAD 路由，我们返回到为给定资源提供的可用的 GET 路由。PHP SAPI 透明地从 HEAD 响应中删除实体体，因此此行为不会影响绝大多数用户。

但是，在 SAPI 环境之外使用 Triangle Router（例如，自定义服务器）的开发者不得发送由 HEAD 请求生成的实体体。如果您不是 SAPI 用户，这是 您的责任；Triangle Router 没有权力阻止您在这种情况下违反 HTTP。

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

作者

这个库基于 Levi Morrison 和 Nikita Popov 实现的路由器 （Levi Morrison） 和 （Nikita Popov）。