README

PHP 的一个快速、灵活且可扩展的 HTTP 路由器。

特性

分组和嵌套分组
易于设计 RESTful API
全面测试
灵活和可扩展
无第三方库依赖
命名参数占位符
检测指定路径的所有请求方法
直观的文档

要求

PHP - 7.0、7.1、7.2 和 master 已测试。

安装

composer require devlibs/routing:1.0.0

文档

include '/path-to-vendor/autoload.php';

use DevLibs\Routing\Router;

// create an router instance
$settings = [
    'middlewares' => [
        'DebugMiddleware',
    ],
];
$router = new Router($settings);

注册处理程序

Router::handle($method, $path, $handler, $settings = null);

method - string 或 array，区分大小写，例如 GET、GET|POST(用 | 分隔，不包含空格)，['GET', 'POST']
path - 路径 MUST 以斜杠 / 开始，例如 /、/users、/users/<username>。
handler - mixed，你想要的任何东西。
settings - 用户定义的设置。

示例

它还提供了一些注册处理程序的快捷方式

Router::delete
Router::get
Router::post
Router::put

$router->get('/', 'handler');

$router->handle('GET|POST', '/users', 'handler');

$router->handle(['GET', 'POST'], '/merchants', 'handler');

$router->get('/users/<username>', 'handler');

$router->get('/orders/<order_id:\d+>', 'handler');

分发请求

Router::dispatch($method, $path);

method - 请求方法，区分大小写。
path - URI 路径

如果匹配，将返回实现 Route 接口的 Route 实例，否则返回 null。

$path = '/users/baz';
$route = $router->dispatch(Router::METHOD_GET, $path);
if (is_null($route)) {
    throw new \Exception('404 Not Found');
}

// handle requset
$handler = $route->handler(); // 'handler'
$params = $route->params(); // ['username' => 'baz']
$settings = $route->settings(); // $settings

Route

类 Route 实现 RouteInterface，提供一些基本方法。

您也可以通过以下代码片段定义自己的 Route 类

Router::$routeClassName = 'namespace\MyRoute';

RouteInterface

Route 类 MUST 实现此接口，有关详细信息，请参阅 RouteInterface。

命名参数占位符

如上所示，路由器具有检测路径参数值的函数。

通常，占位符模式必须是 <name> 或 <name:regex> 之一，它将被转换为 ([^/]+) 和 (regex)，您也可以通过替换 Router::$replacePatterns 和 Router::$replacements 来更改它。

设置

您可以通过 settings 扩展路由器，例如 param 的默认值和 middleware 等，但这不属于本文档的范围。

分组

分组是路由器的强大功能，用于分离模块或 API 的版本。此库也实现了此功能，它允许嵌套分组。

Router::group($prefix, array $settings = []);

prefix - 分组前缀，它 MUST NOT 包含斜杠 /。
settings - 扩展设置，它将继承父级设置。

// grouping
$v1Settings = [
    'version' => '1',
    'middlewares' => [
        'AuthMiddleware',
    ],
];
$v1 = $router->group('v1', $v1Settings);
$v1->get('/hello', 'hello');
$route = $router->dispatch(Router::METHOD_GET, '/v1/hello'); // matched
/**
 * [
 *     'version' => '1',
 *     'middlewares' => [
 *         'DebugMiddleware',
 *         'AuthMiddleware',
 *     ],
 * ];
 */
 var_dump($route->settings());

// nested group
$v1Users = $v1->group('users');
$v1Users->get('/', 'users');
$v1Users->get('/<name>', 'user profile');
$route = $router->dispatch(Router::METHOD_GET, '/v1/users'); // matched
$route = $router->dispatch(Router::METHOD_GET, '/v1/users/bar'); // matched

RESTful API

如上所示，显然很容易设计 RESTful API 应用程序。

$router->get('/products', 'products');
$router->post('/products', 'create product');
$router->get('/products/<product_id:\d+>', 'product detail');
$router->put('/products/<product_id:\d+>', 'update product');
$router->delete('/products/<product_id:\d+>', 'delete product');

检测方法

考虑到 OPTIONS 请求，它提供了一个用于检测指定 URI 路径所有有效方法的 API。

Route::getAllowMethods($path, $methods = null);

path - 请求 URL 路径
methods - Router::$methods 定义了一些常用请求方法，但它不包括所有请求方法，您可以在 Router::$methods 中指定方法，如果键方法不是 Router::$methods 之一。

$allowMethods = $router->getAllowMethods('/merchants'); // ['GET', 'POST']

常见问题解答

包未找到

当 composer 抱怨 "无法找到包 devlibs/routing" 时，请将以下存储库添加到 repositories。

{
    "type": "git",
    "url": "https://github.com/devlibs/routing.git"
}

devlibs / routing

维护者

详细信息