路由庫 FastRoute · 小唐 PHP筆記

## composer 安裝FastRoute ~~~ composer require nikic/fast-route ~~~ ## 用法這是一個基本的用法示例： ~~~ <?php require '/path/to/vendor/autoload.php'; $dispatcher = FastRoute\simpleDispatcher(function(FastRoute\RouteCollector $r) { $r->addRoute('GET', '/users', 'get_all_users_handler'); // {id} must be a number (\d+) $r->addRoute('GET', '/user/{id:\d+}', 'get_user_handler'); // The /{title} suffix is optional $r->addRoute('GET', '/articles/{id:\d+}[/{title}]', 'get_article_handler'); }); // 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); $routeInfo = $dispatcher->dispatch($httpMethod, $uri); switch ($routeInfo[0]) { case FastRoute\Dispatcher::NOT_FOUND: // ... 404 Not Found break; case FastRoute\Dispatcher::METHOD_NOT_ALLOWED: $allowedMethods = $routeInfo[1]; // ... 405 Method Not Allowed break; case FastRoute\Dispatcher::FOUND: $handler = $routeInfo[1]; $vars = $routeInfo[2]; // ... call $handler with $vars break; } ~~~ ### 定義路線路由是通過調用`FastRoute\simpleDispatcher()`函數來定義的，該函數接受一個可調用`FastRoute\RouteCollector`實例。通過調用`addRoute()`收集器實例來添加路由： ~~~html $r->addRoute($method, $routePattern, $handler); ~~~ 是一個大寫的`$method`HTTP 方法字符串，某個路由應該與之匹配。可以使用數組指定多個有效方法： ~~~html // 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`使用語法 where`{foo}`指定占位符名稱`foo`并匹配正則表達式`[^/]+`。要調整占位符匹配的模式，您可以通過編寫指定自定義模式`{bar:[0-9]+}`。一些例子： ~~~html // 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`。可選部件僅支持尾部位置，不支持路線中間。 ~~~html // 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`參數不一定是回調，它也可以是控制器類名或您希望與路由關聯的任何其他類型的數據。FastRoute 只告訴您哪個處理程序對應于您的 URI，您如何解釋它取決于您。 #### [](https://github.com/nikic/FastRoute#shortcut-methods-for-common-request-methods)常用請求方法的快捷方式對于`GET`、`POST`、`PUT`、和請求方法`PATCH`，可以使用快捷方式。例如：`DELETE``HEAD` ~~~html $r->get('/get-route', 'get_handler'); $r->post('/post-route', 'post_handler'); ~~~ 相當于： ~~~html $r->addRoute('GET', '/get-route', 'get_handler'); $r->addRoute('POST', '/post-route', 'post_handler'); ~~~ #### [](https://github.com/nikic/FastRoute#route-groups)路由組此外，您可以在組內指定路由。一個組內定義的所有路由都有一個共同的前綴。例如，將您的路線定義為： ~~~html $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'); }); ~~~ 將具有與以下相同的結果： ~~~html $r->addRoute('GET', '/admin/do-something', 'handler'); $r->addRoute('GET', '/admin/do-another-thing', 'handler'); $r->addRoute('GET', '/admin/do-something-else', 'handler'); ~~~ 還支持嵌套組，在這種情況下，所有嵌套組的前綴都被組合在一起。 ### [](https://github.com/nikic/FastRoute#caching)緩存接受用于定義路由的回調的原因`simpleDispatcher`是允許無縫緩存。通過使用`cachedDispatcher`instead of`simpleDispatcher`你可以緩存生成的路由數據并從緩存的信息構造調度程序： ~~~html <?php $dispatcher = FastRoute\cachedDispatcher(function(FastRoute\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', /* required */ 'cacheDisabled' => IS_DEBUG_ENABLED, /* optional, enabled by default */ ]); ~~~ 該函數的第二個參數是一個選項數組，可用于指定緩存文件位置等。 ### [](https://github.com/nikic/FastRoute#dispatching-a-uri)調度 URI 通過調用`dispatch()`創建的調度程序的方法來調度 URI。此方法接受 HTTP 方法和 URI。獲取這兩位信息（并適當地規范化它們）是您的工作——該庫未綁定到 PHP Web SAPI。該`dispatch()`方法返回一個數組，其第一個元素包含狀態代碼。它是`Dispatcher::NOT_FOUND`,`Dispatcher::METHOD_NOT_ALLOWED`和之一`Dispatcher::FOUND`。對于方法不允許狀態，第二個數組元素包含提供的 URI 允許的 HTTP 方法列表。例如： ~~~ [FastRoute\Dispatcher::METHOD_NOT_ALLOWED, ['GET', 'POST']] ~~~ > **注意：**HTTP 規范要求`405 Method Not Allowed`響應包含`Allow:`標頭以詳細說明所請求資源的可用方法。使用 FastRoute 的應用程序在中繼 405 響應時應使用第二個數組元素添加此標頭。對于 found 狀態，第二個數組元素是與路由關聯的處理程序，第三個數組元素是占位符名稱與其值的字典。例如： ~~~ /* Routing against GET /user/nikic/42 */ [FastRoute\Dispatcher::FOUND, 'handler0', ['name' => 'nikic', 'id' => '42']] ~~~ ### [](https://github.com/nikic/FastRoute#overriding-the-route-parser-and-dispatcher)覆蓋路由解析器和調度器路由過程使用三個組件：路由解析器、數據生成器和調度器。這三個組件遵循以下接口： ~~~html <?php namespace FastRoute; 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); } ~~~ 路由解析器采用路由模式字符串并將其轉換為路由信息數組，其中每個路由信息又是其部分的數組。使用示例可以最好地理解該結構： ~~~ /* The route /user/{id:\d+}[/{name}] converts to the following array: */ [ [ '/user/', ['id', '\d+'], ], [ '/user/', ['id', '\d+'], '/', ['name', '[^/]+'], ], ] ~~~ 然后可以將該數組傳遞給`addRoute()`數據生成器的方法。添加所有路由后`getData()`，將調用生成器的，它返回調度程序所需的所有路由數據。此數據的格式未進一步指定 - 它與相應的調度程序緊密耦合。調度程序通過構造函數接受路由數據并提供`dispatch()`您已經熟悉的方法。路由解析器可以單獨重寫（以使用一些不同的模式語法），但是數據生成器和調度器應該始終成對更改，因為前者的輸出與后者的輸入緊密耦合。生成器和調度器分開的原因是在使用緩存時只需要后者（因為前者的輸出是被緩存的。）當使用上面的`simpleDispatcher`/`cachedDispatcher`函數時，覆蓋通過選項數組發生： ~~~html <?php $dispatcher = FastRoute\simpleDispatcher(function(FastRoute\RouteCollector $r) { /* ... */ }, [ 'routeParser' => 'FastRoute\\RouteParser\\Std', 'dataGenerator' => 'FastRoute\\DataGenerator\\MarkBased', 'dispatcher' => 'FastRoute\\Dispatcher\\MarkBased', ]); ~~~ 上面的選項數組對應于默認值。通過替換`MarkBased`為，`GroupCountBased`您可以切換到不同的調度策略。 ### [](https://github.com/nikic/FastRoute#a-note-on-head-requests)關于 HEAD 請求的注釋 HTTP 規范要求服務器同時[支持 GET 和 HEAD 方法](http://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html#sec5.1.1 "RFC 2616 第 5.1.1 節")： > 所有通用服務器都必須支持 GET 和 HEAD 方法為了避免強制用戶為每個資源手動注冊 HEAD 路由，我們回退到為給定資源匹配可用的 GET 路由。PHP web SAPI 透明地從 HEAD 響應中刪除了實體主體，因此這種行為對絕大多數用戶沒有影響。但是，在 Web SAPI 環境（例如自定義服務器）之外使用 FastRoute 的實施者不得發送為響應 HEAD 請求而生成的實體主體。如果您是非 SAPI 用戶，這是*您的責任*；在這種情況下，FastRoute 沒有權限阻止您破壞 HTTP。最后，請注意應用程序可以始終為給定資源指定自己的 HEAD 方法路由以完全繞過此行為