README

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

中间件栈 - 向您的路由添加一些中间件
路由生成 - 对于命名路由，您可以生成一个路径
通过 max phpstan - 可能更少错误 :P

安装

使用 composer 安装

composer require crazy-goat/router

需要PHP 7.1或更高版本。

用法

以下是一个基本用法示例

<?php

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

$routing = function (CrazyGoat\Router\RouteCollector $r) {
    $r->get('/users', 'get_all_users_handler');
    // {id} must be a number (\d+)
    $r->get('/user/{id:\d+}', 'get_user_handler');
    // The /{title} suffix is optional
    $r->get('/articles/{id:\d+}[/{title}]', 'get_article_handler');
};

$dispatcher = CrazyGoat\Router\DispatcherFactory::createFromClosure($routing);

// 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->getHandler();
    $params = $routeInfo->getVariables();
    $middlewareStack = $routeInfo->getMiddlewareStack();
    
    // ... call $handler with $vars
} catch (\CrazyGoat\Router\Exceptions\MethodNotAllowed $exception) {
    // ... 405 Method Not Allowed
} catch (\CrazyGoat\Router\Exceptions\RouteNotFound $exception) {
   // ... 404 Not Found
}

定义路由

路由是通过调用 CrazyGoat\Router\DispatcherFactory::createFromClosure() 或函数定义的，该函数接受一个接受 CrazyGoat\Router\RouteCollector 实例的可调用对象。通过在收集器实例上调用 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 参数不一定是回调，它也可以是控制器类名或您希望与路由关联的任何其他类型的数据。CrazyGoat\Router 只会告诉你哪个处理程序与您的 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 (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');

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

缓存

通过使用 cachedDispatcher 而不是 simpleDispatcher，您可以缓存生成的路由数据，并从缓存的信息中构建分发器

<?php
$dispatcher = DispatcherFactory::createFileCached('data/router-file.php', 'cache/router.cache');

第一个参数是包含路由定义的文件。该文件应返回包含路由定义的 Closure

<?php
return function (CrazyGoat\Router\RouteCollector $r) {
    $r->get('/users', 'get_all_users_handler');
    // {id} must be a number (\d+)
    $r->get('/user/{id:\d+}', 'get_user_handler');
    // The /{title} suffix is optional
    $r->get('/articles/{id:\d+}[/{title}]', 'get_article_handler');
};

第二个参数是缓存文件的路径。如果缓存文件不存在，则从第一个参数加载路由数据。

分发URI

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

《dispatch()` 方法返回一个包含处理程序、变量和中间件栈信息的 RouteInfo 对象。如果没有路由与请求 URI 匹配，将抛出 RouteNotFound 异常。如果找到路由但方法与请求方法不匹配，则将抛出 MethodNotAllowed 异常。您可以使用 getAllowedMethods() 函数从异常中获取允许的方法。

<?php
try {
    $routeInfo = $dispatcher->dispatch($httpMethod, $uri);
    // ... your code 
} catch (\CrazyGoat\Router\Exceptions\MethodNotAllowed $exception) {
    $allowedMethods = $exception->getAllowedMethods();
}

注意：HTTP 规范要求 405 Method Not Allowed 响应包含 Allow: 标头，以详细说明请求资源的可用方法。使用 CrazyGoat\Router 的应用程序应在转接 405 响应时使用 getAllowedMethods() 返回的数组来添加此标头。

对于找到的状态，RouteInfo 对象包含与路由关联的处理程序、占位符名称到其值的字典和中间件栈。例如

$routeInfo = $dispatcher->dispatch($httpMethod, $uri);
    
$handler = $routeInfo->getHandler();
$params = $routeInfo->getVariables();
$middlewareStack = $routeInfo->getMiddlewareStack();

覆盖路由解析器和分发器

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

<?php

namespace CrazyGoat\Router;

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

interface DataGenerator {
    public function addRoute(string $httpMethod, array $routeData, string $handler, array $middleware = [], ?string $name = null): void;
    public function getData(): array;
    public function hasNamedRoute(string $name): bool;
}

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

    public function dispatch(string $httpMethod, string $uri): RouteInfo;
    public function setData(array $data): void;
}

路由解析器接受一个路由模式字符串并将其转换为包含路由信息的数组，其中每个路由信息又是一个其部分的数组。最佳理解方式是使用示例

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

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

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

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

要使用自定义解析器、生成器或分发器，请创建新的 Configuration 对象，并将其传递给 DispatcherFactory::prepareDispatcher() 函数。

<?php

$config = new Configuration(
    new ClosureProvider($routingData),
    new RouteCollector(
        new CustomParser(),
        New CustomDataGenerator()
    ),
    new CustomDispatcher()       
);

中间件

将中间件添加到路由非常简单，只需将 middleware 参数传递给 RouteCollector 中的 addRoute() 或 addGroup() 方法。

$dispatcher = DispatcherFactory::createFromClosure(function(CrazyGoat\Router\RouteCollector $r) {
    $r->addRoute(['GET'], '/users', 'get_all_users_handler', ['root_middleware']);
    $r->addGroup('/nested', function (CrazyGoat\Router\RouteCollector $r) {
        $r->addRoute(['GET'], '/users', 'handler3', ['nested-middleware']);
    }, ['group_middleware']);
});

对于第一个路由 /users，将只返回 root_middleware。对于嵌套路由，如 /nested/users，将返回中间件 group_middleware 和 nested-middleware。您还可以将多个中间件添加到路由。

    $r->addRoute(['GET'], '/users', 'get_all_users_handler', ['first', 'second']);

中间件栈在 routeInfo 的第三个索引处返回。如果没有将中间件添加到路由，则将返回空数组。

$r->addRoute(['GET'], '/users', 'get_all_users_handler', ['first', 'second']);

//some usefull code

$routeInfo = $dispatcher->dispatch($httpMethod, $uri);
$middlewares = $routeInfo->getMiddlewareStack();

命名路由和路径生成

CrazyRoute 提供了一种生成命名路由路径的简单方法。首先，我们必须添加一个带有名称的路由。名称作为 addRoute() 函数的第五个参数传递。路由名称必须是唯一的，否则将抛出 BadRouteException 异常。现在我们只需要在 Dispatcher 对象上调用 produce() 函数。

$r->addRoute(['GET'], '/users', 'get_all_users_handler', [], 'users');

// some crazy code

$path = $dispatcher->produce('users', $route_params);

必须将所有必需的路由参数传递给第二个参数，否则将抛出异常。

关于 HEAD 请求的注意事项

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

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

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

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

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

致谢

此库基于由Nikita Popov开发的FastRoute。

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

crazy-goat / router

维护者

详细信息