README

为 PSR-7 提供的 FastRoute 包装器。

要求

PHP >= 7.0 是必需的，但推荐使用 PHP 的最新稳定版本。

安装

$ composer require atanvarno/router:^0.2.0

基本用法

提供两种路由器：SimpleRouter 和 CachedRouter。这两个都实现了 Router 接口。

实例化

// A simple, non-caching, router:
use Atanvarno\Router\SimpleRouter;
$router = new SimpleRouter();

// A caching router:
use Atanvarno\Router\CachedRouter;
$router = new CachedRouter();

默认情况下，使用 GroupCountBased FastRoute 驱动程序。可以在路由器构造函数中使用 Router::DRIVER_* 常量指定其他驱动程序。

请参阅 SimpleRouter::__construct() 和 CachedRouter::__construct()。

定义路由

可以通过使用 add() 方法、addGroup() 方法或通过构造函数注入来定义路由。每个 HTTP 方法也有快捷方法。

`add()`

$router->add($method, $pattern, $handler);

$method 是一个用于特定路由匹配的大写 HTTP 方法字符串。可以使用数组指定多个有效方法。每个有效 HTTP 方法都有一个 Router::METHOD_* 常量。

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

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

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

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

add() 实现了流畅接口，允许进行多个调用并串联。

请参阅 Router::add()。

`addGroup()`

您可以在组内指定路由。组内定义的所有路由都将有一个共同的前缀。

例如，将路由定义为

$router->addGroup(
    '/admin',
    [
        [Router::METHOD_GET, '/user/{name}', 'handler']
        [Router::METHOD_DELETE, '/user/{name}', 'handler'],
    ]
);

将产生与以下相同的结果

$router->add(Router::METHOD_GET, '/admin/user/{name}', 'handler')
    ->add(Router::METHOD_DELETE, '/admin/user/{name}', 'handler');

addGroup() 实现了流畅接口，允许进行多个调用并串联。

请参阅 Router::addGroup()。

构造函数注入

路由信息可以注入到 Router 实例构造函数中。该参数接受一个包含 $method、$pattern 和 $handler 值的数组数组的数组，类似于对 add() 的调用。

这允许将路由存储在单独的配置文件中，该文件返回这样的数组

<?php // routes.php
use Atanvarno\Router\Router;

return [
    [Router::METHOD_GET, '/user[/{id:\d+}[/{name}]]', 'handler'],
    [Router::METHOD_PATCH, '/table/{tid}/{uid}/{data}', 'handler'],
    //...
];

<?php // main.php
use Atanvarno\Router\{Router, SimpleRouter};

$router = new SimpleRouter(Router::DRIVER_GROUP_COUNT, include 'path/to/routes.php');

请参阅 SimpleRouter::__construct() 和 CachedRouter::__construct()。

快捷方法

对于所有有效的 HTTP 请求方法，都提供了快捷方法。例如

$router->get('/get-route', 'get_handler')
    ->post('/post-route', 'post_handler');
// Is equivalent to:
$router->add(Router::METHOD_GET, '/get-route', 'get_handler')
    ->add(Router::METHOD_POST, '/post-route', 'post_handler');

快捷方法实现了一个流畅的接口，允许链式调用多个方法。

请参阅 Router。

分发

通过调用 dispatch() 方法来分发请求。此方法接受一个 PSR-7 RequestInterface 实例。

$request = //... define your PSR-7 request.

$result = $router->dispatch($request);

请注意，所有 URI 路径都已标准化，因此它们没有尾部斜杠，并且以一个前导斜杠开始。所有用户提供的模式也相应地进行了标准化。

dispatch() 返回一个数组，其第一个元素包含一个状态码。它可以是 FastRoute\Dispatcher::NOT_FOUND、FastRoute\Dispatcher::METHOD_NOT_ALLOWED 或 FastRoute\Dispatcher::FOUND。对于不允许的方法状态，第二个数组元素包含允许用于所提供请求的 HTTP 方法列表。

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

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

// Routing against GET /user/atan/42
[FastRoute\Dispatcher::FOUND, 'handler0', ['name' => 'atan', 'id' => '42']]

请参阅 Router::dispatch()。

缓存

除了使用 SimpleRouter，您还可以使用 CachedRouter。

CachedRouter 需要一个 PSR-16 缓存对象作为构造函数参数。

默认情况下，CachedRouter 将直接从缓存获取其分发数据，并绕过由 add() 调用或构造函数注入定义的路由。在没有分发数据可用的情况下（例如第一次 dispatch() 调用或缓存数据已过期时），CachedRouter 将从定义的路由生成分发数据并将其存储在缓存中。

如果您的路由配置已更改并且您需要更新缓存中的分发数据，请调用 refreshCache()。

请参阅 CachedRouter。

异常

所有抛出的异常都实现了接口 RouterException。

而不是提供 array 结果，dispatch() 可以抛出异常来处理找不到和不允许的方法结果。 MethodNotAllowedException::getAllowed() 为所需的 Allow: 响应头提供了允许的方法列表。

该软件包包含以下异常

关于 HEAD 请求的注意事项

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

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

为了避免强制用户为每个资源手动注册 HEAD 路由，我们回退到为给定资源匹配可用的 GET 路由。应用程序可以选择始终为给定资源指定自己的 HEAD 方法路由，以完全绕过此行为。

完整 API

请参阅 API。

atanvarno / router

维护者

详细信息