README

一个轻量级且简单的面向对象PHP路由器。由Bramus Van Damme (https://www.bram.us) 和贡献者构建

注意

从 Bramus Router 分支，以下是一些变更

支持在路由器上使用PHP-Di依赖注入容器，因此我们可以在构造函数中使用DI；
支持多个嵌套路由组；
添加路由异常以捕获路由问题，否则即使在出现错误的情况下也不会返回任何内容；

特性

支持 GET、POST、PUT、DELETE、OPTIONS、PATCH 和 HEAD 请求方法
路由简写，如 get()、post()、put() 等
静态路由模式
动态路由模式：基于PCRE的动态路由模式或基于占位符的动态路由模式
可选路由子模式
支持 X-HTTP-Method-Override 头部
子路由/挂载路由
允许 Class@Method 调用
自定义404处理
路由前的中间件
路由前的路由中间件/应用中间件
路由后的路由中间件/应用中间件（完成回调）
在子目录中运行良好

先决条件/需求

PHP 5.3或更高版本
URL重写

安装

可以使用Composer进行安装

composer require bramus/router ~1.6

演示

演示包含在 demo 子目录中。使用您喜欢的Web服务器或使用PHP 5.4+的内置服务器（在shell中执行 php -S localhost:8080）来提供服务。包含用于Apache的 .htaccess。

此外，还包括一个多语言路由器的演示。这可以在 demo-multilang 子目录中找到，并以与常规演示相同的方式运行。

用法

创建一个 \Bramus\Router\Router 实例，在其上定义一些路由，并运行它。

// Require composer autoloader
require __DIR__ . '/vendor/autoload.php';

// Create Router instance
$router = new \Bramus\Router\Router();

// Define routes
// ...

// Run it!
$router->run();

路由

使用 $router->match(method(s), pattern, function) 将路由（一种或多种HTTP方法与模式的组合）钩入

$router->match('GET|POST', 'pattern', function() { … });

bramus/router 支持 GET、POST、PUT、PATCH、DELETE、HEAD（见说明）和 OPTIONS HTTP请求方法。传入单个请求方法，或使用 | 分隔的多个请求方法。

当路由与当前URL匹配时（例如 $_SERVER['REQUEST_URI']），将执行附加的 路由处理函数。路由处理函数必须是一个可调用。只有第一个匹配的路由将被处理。当没有找到匹配的路由时，将执行404处理程序。

路由简写

提供单个请求方法的简写

$router->get('pattern', function() { /* ... */ });
$router->post('pattern', function() { /* ... */ });
$router->put('pattern', function() { /* ... */ });
$router->delete('pattern', function() { /* ... */ });
$router->options('pattern', function() { /* ... */ });
$router->patch('pattern', function() { /* ... */ });

您可以使用此简写来访问可以使用任何方法的路由

$router->all('pattern', function() { … });

注意：必须在调用 $router->run(); 之前将路由钩入。

注意：没有为 match() 提供简写，因为 bramus/router 会将此类请求内部重定向到等效的 GET 请求，以符合RFC2616规范（见说明）。

路由模式

路由模式可以是静态的或动态的

静态路由模式不包含动态部分，必须与当前URL的path部分完全匹配。
动态路由模式包含可以随请求而变化的动态部分。这些变化的部分被称为子模式，可以使用Perl兼容正则表达式（PCRE）或使用占位符来定义。

静态路由模式

静态路由模式是表示URI的普通字符串。它将直接与当前URL的path部分进行比较。

示例

/about
/contact

使用示例

// This route handling function will only be executed when visiting http(s)://www.example.org/about
$router->get('/about', function() {
    echo 'About Page Contents';
});

基于PCRE的动态路由模式

此类路由模式包含可以随请求而变化的动态部分。这些变化的部分被称为子模式，并使用正则表达式进行定义。

示例

/movies/(\d+)
/profile/(\w+)

动态路由模式中常用的基于PCRE的子模式包括

\d+ = 一个或多个数字（0-9）
\w+ = 一个或多个单词字符（a-z 0-9 _）
[a-z0-9_-]+ = 一个或多个单词字符（a-z 0-9 _）和破折号（-）
.* = 任何字符（包括/），零个或多个
[^/]+ = 任何非/字符，一个或多个

注意：PHP PCRE速查表可能很有用。

动态PCRE路由模式中定义的子模式将被转换为参数，传递给路由处理函数。前提是这些子模式需要定义为括号子模式，这意味着它们应该被括号包围。

// Bad
$router->get('/hello/\w+', function($name) {
    echo 'Hello ' . htmlentities($name);
});

// Good
$router->get('/hello/(\w+)', function($name) {
    echo 'Hello ' . htmlentities($name);
});

注意：路由模式开头处的/是可选的，但建议使用。

当定义多个子模式时，结果的路由处理参数将按定义的顺序传递给路由处理函数。

$router->get('/movies/(\d+)/photos/(\d+)', function($movieId, $photoId) {
    echo 'Movie #' . $movieId . ', photo #' . $photoId;
});

基于占位符的动态路由模式

此类路由模式与基于PCRE的动态路由模式相同，但有一个区别：它们不是使用正则表达式进行模式匹配，而是使用更简单的占位符。占位符是包围在花括号中的字符串，例如{name}。您不需要在占位符周围添加括号。

示例

/movies/{id}
/profile/{username}

占位符比PRCEs更容易使用，但提供的控制较少，因为它们在内部被转换为匹配任何字符的正则表达式（.*）。

$router->get('/movies/{movieId}/photos/{photoId}', function($movieId, $photoId) {
    echo 'Movie #' . $movieId . ', photo #' . $photoId;
});

注意：占位符的名称不需要与传递给路由处理函数的参数名称匹配。

$router->get('/movies/{foo}/photos/{bar}', function($movieId, $photoId) {
    echo 'Movie #' . $movieId . ', photo #' . $photoId;
});

可选路由子模式

可以通过在子模式后添加一个?来使路由子模式可选。以博客URL为例，形式为/blog(/year)(/month)(/day)(/slug)

$router->get(
    '/blog(/\d+)?(/\d+)?(/\d+)?(/[a-z0-9_-]+)?',
    function($year = null, $month = null, $day = null, $slug = null) {
        if (!$year) { echo 'Blog overview'; return; }
        if (!$month) { echo 'Blog year overview'; return; }
        if (!$day) { echo 'Blog month overview'; return; }
        if (!$slug) { echo 'Blog day overview'; return; }
        echo 'Blogpost ' . htmlentities($slug) . ' detail';
    }
);

上面的代码片段响应以下URL：/blog、/blog/year、/blog/year/month、/blog/year/month/day和/blog/year/month/day/slug。

注意：使用可选参数时，重要的一点是将子模式的开头/放入子模式本身中。别忘了为可选参数设置默认值。

不幸的是，上面的代码片段还响应了类似/blog/foo的URL，并声明需要显示概览，这是不正确的。可以通过扩展括号子模式来使可选子模式连续，使它们包含其他可选子模式：模式应类似于/blog(/year(/month(/day(/slug))))而不是之前的/blog(/year)(/month)(/day)(/slug)。

$router->get('/blog(/\d+(/\d+(/\d+(/[a-z0-9_-]+)?)?)?)?', function($year = null, $month = null, $day = null, $slug = null) {
    // ...
});

注意：强烈建议始终定义连续的可选参数。

使用量词来要求URL中正确数量的数字。

$router->get('/blog(/\d{4}(/\d{2}(/\d{2}(/[a-z0-9_-]+)?)?)?)?', function($year = null, $month = null, $day = null, $slug = null) {
    // ...
});

子路由/挂载路由

使用$router->mount($baseroute, $fn)将一组路由挂载到子路由模式。子路由模式将添加到当前作用域中定义的所有后续路由之前。例如，将回调$fn挂载到/movies，则将/movies添加到所有后续路由之前。

$router->mount('/movies', function() use ($router) {

    // will result in '/movies/'
    $router->get('/', function() {
        echo 'movies overview';
    });

    // will result in '/movies/id'
    $router->get('/(\d+)', function($id) {
        echo 'movie id ' . htmlentities($id);
    });

});

子路由嵌套是可能的，只需在已包含在前面$router->mount()调用中的可调用对象中定义第二个$router->mount()即可。

`Class@Method`调用

我们可以这样路由到类操作：

$router->get('/(\d+)', '\App\Controllers\User@showProfile');

当请求匹配指定的路由URI时，User类上的showProfile方法将被执行。定义的路由参数将被传递到类方法。

方法可以是静态的（推荐）或非静态的（不推荐）。在非静态方法的情况下，将创建类的新实例。

如果你的大多数/所有处理类都在同一个命名空间中，你可以通过setNamespace()设置在路由实例上使用的默认命名空间。

$router->setNamespace('\App\Controllers');
$router->get('/users/(\d+)', 'User@showProfile');
$router->get('/cars/(\d+)', 'Car@showProfile');

自定义404

默认的404处理器设置404状态代码并退出。你可以通过使用$router->set404(callable)来覆盖默认的404处理器。

$router->set404(function() {
    header('HTTP/1.1 404 Not Found');
    // ... do something special here
});

你还可以定义多个自定义路由，例如，如果你想定义一个/api路由，你可以打印一个自定义的404页面。

$router->set404('/api(/.*)?', function() {
    header('HTTP/1.1 404 Not Found');
    header('Content-Type: application/json');

    $jsonArray = array();
    $jsonArray['status'] = "404";
    $jsonArray['status_text'] = "route not defined";

    echo json_encode($jsonArray);
});

也支持Class@Method调用

$router->set404('\App\Controllers\Error@notFound');

当没有路由模式与当前URL匹配时，将执行404处理器。

💡你也可以通过调用$router->trigger404()手动触发404处理器。

$router->get('/([a-z0-9-]+)', function($id) use ($router) {
    if (!Posts::exists($id)) {
        $router->trigger404();
        return;
    }

    // …
});

路由前的中间件

bramus/router支持Before Route Middlewares，它们在路由处理之前执行。

就像路由处理函数一样，你可以将处理函数连接到一个或多个HTTP请求方法和特定的路由模式。

$router->before('GET|POST', '/admin/.*', function() {
    if (!isset($_SESSION['user'])) {
        header('location: /auth/login');
        exit();
    }
});

与路由处理函数不同，当找到多个路由匹配时，将执行多个路由中间件。

路由中间件

路由中间件是针对特定路由的。使用通用路由模式（即所有URL），它们可以成为Before Router Middlewares（在其他项目中有时称为before app middlewares），无论请求的URL是什么，都会始终执行。

$router->before('GET', '/.*', function() {
    // ... this will always be executed
});

路由之后中间件/运行回调

运行一个（1）个中间件函数，命名在路由处理之后运行的After Router Middleware（在其他项目中有时称为after app middlewares）。只需通过$router->run()函数传递即可。运行回调与路由无关。

$router->run(function() { … });

注意：如果路由处理函数已调用exit()，则不会运行运行回调。

覆盖请求方法

使用X-HTTP-Method-Override来覆盖HTTP请求方法。仅当原始请求方法是POST时才有效。允许的X-HTTP-Method-Override值是PUT、DELETE或PATCH。

子目录支持

默认情况下，bramus/router可以在任何（子）目录中运行……不需要调整你的代码。你可以自由地移动你的入口脚本index.php，路由器会自动根据当前文件夹的路径相对地挂载所有路由到该basePath。

假设你有一个服务器托管域名www.example.org，使用public_html/作为其文档根，并使用这个小入口脚本index.php。

$router->get('/', function() { echo 'Index'; });
$router->get('/hello', function() { echo 'Hello!'; });

如果你将此文件（及其随附的.htaccess文件等）放置在文档根级别（例如public_html/index.php），则bramus/router会将所有路由挂载到域名根（例如/），因此响应于https://www.example.org/和https://www.example.org/hello。
如果您要将此文件（及其随附的 .htaccess 文件或类似文件）移动到子文件夹中（例如 public_html/demo/index.php），bramus/router 将将所有路由挂载到当前路径上（例如 /demo），因此将响应 https://www.example.org/demo 和 https://www.example.org/demo/hello。在这种情况下，无需使用 $router->mount(…)。

禁用子文件夹支持

如果您不希望 bramus/router 自动适应其放置的文件夹，可以通过调用 setBasePath() 手动覆盖 basePath。这在 （不常见） 的情况下是必要的，即您的 入口脚本 和您的 入口URL 并没有紧密耦合 （例如，当入口脚本放置在不需要包含在URL中响应的子文件夹中时）。

// Override auto base path detection
$router->setBasePath('/');

$router->get('/', function() { echo 'Index'; });
$router->get('/hello', function() { echo 'Hello!'; });

$router->run();

如果您要将此文件放置在子文件夹中（例如 public_html/some/sub/folder/index.php），它仍然会将路由挂载到域名根目录（例如 /），因此将响应 https://www.example.org/ 和 https://www.example.org/hello （假设您的 .htaccess 文件——放置在文档根目录级别——重写请求到它）

与其他库的集成

通过使用 use 关键字将依赖项传递到处理函数中，将其他库与 bramus/router 集成。

$tpl = new \Acme\Template\Template();

$router->get('/', function() use ($tpl) {
    $tpl->load('home.tpl');
    $tpl->setdata(array(
        'name' => 'Bramus!'
    ));
});

$router->run(function() use ($tpl) {
    $tpl->display();
});

在这种情况下，仍然可以在 After Router 中间件中操作输出

关于使用 PUT 的说明

PHP 中没有 $_PUT 这样的东西。必须伪造它

$router->put('/movies/(\d+)', function($id) {

    // Fake $_PUT
    $_PUT  = array();
    parse_str(file_get_contents('php://input'), $_PUT);

    // ...

});

关于发起 HEAD 请求的说明

在发起 HEAD 请求时，所有输出都将被缓冲，以防止任何内容流入响应体，如 RFC2616 (Hypertext Transfer Protocol -- HTTP/1.1) 中定义的那样

HEAD 方法与 GET 方法相同，但服务器必须不在响应中返回消息体。对 HEAD 请求的响应中包含的 HTTP 头中的元信息应该与对 GET 请求的响应中发送的元信息相同。此方法可以用于获取由请求暗示的实体的元信息，而不传输实体主体。此方法通常用于测试超文本链接的有效性、可访问性和最近修改。

为了实现这一点，bramus/router 会将内部的 HEAD 请求重定向到等效的 GET 请求，并自动抑制所有输出。

单元测试和代码覆盖率

bramus/router 随带使用 PHPUnit 的单元测试。

如果已全局安装 PHPUnit，则运行 phpunit 以运行测试。
如果未全局安装 PHPUnit，则通过运行 composer install --dev 在本地安装它。通过调用 vendor/bin/phpunit 运行测试。

包含的 composer.json 还将安装 php-code-coverage，允许您生成 代码覆盖率报告。运行 phpunit --coverage-html ./tests-report（需要 XDebug），报告将放置在 tests-report 子文件夹中。

致谢

bramus/router 受到 Klein、Ham 和 JREAM/route 的启发。虽然 Klein 提供了许多功能，但它不是面向对象的。虽然 Ham 是面向对象的，但它不擅长 关注点分离，因为它还在路由类中提供了模板。

许可

bramus/router 在 MIT 公共许可证下发布。有关详细信息，请参阅所附的 LICENSE。

celsomtrindade / router

维护者

详细信息

README

注意

特性

先决条件/需求

安装

演示

用法

路由

路由简写

路由模式

静态路由模式

基于PCRE的动态路由模式

基于占位符的动态路由模式

可选路由子模式

子路由/挂载路由

`Class@Method`调用

自定义404

路由前的中间件

路由中间件

路由之后中间件/运行回调

覆盖请求方法

子目录支持

禁用子文件夹支持

与其他库的集成

关于使用 PUT 的说明

关于发起 HEAD 请求的说明

单元测试和代码覆盖率

致谢

许可

celsomtrindade / router

维护者

详细信息

README

注意

特性

先决条件/需求

安装

演示

用法

路由

路由简写

路由模式

静态路由模式

基于PCRE的动态路由模式

基于占位符的动态路由模式

可选路由子模式

子路由/挂载路由

Class@Method调用

自定义404

路由前的中间件

路由中间件

路由之后中间件/运行回调

覆盖请求方法

子目录支持

禁用子文件夹支持

与其他库的集成

关于使用 PUT 的说明

关于发起 HEAD 请求的说明

单元测试和代码覆盖率

致谢

许可

`Class@Method`调用