路由參數 · ThinkPHP5.1完全開發手冊

## 路由參數路由分組及規則定義支持指定路由參數，這些參數主要完成路由匹配檢測以及行為執行。`5.1`版本極大改進了路由參數的用法。 >[danger] 路由參數可以在定義路由規則的時候直接傳入（批量），不過`5.1`采用了更加面向對象的方式進行路由參數配置，因此使用方法配置更加清晰。 |參數|說明|方法名| |---|---|---| |method|請求類型檢測，支持多個請求類型|method| |ext|URL后綴檢測，支持匹配多個后綴|ext| |deny_ext|URL禁止后綴檢測，支持匹配多個后綴|denyExt| |https|檢測是否https請求|https| |domain|域名檢測|domain| |before|前置行為（檢測）|before| |after|后置行為（執行）|after| |merge_extra_vars| 合并額外參數|mergeExtraVars| |complete_match|是否完整匹配路由|completeMatch| |model|綁定模型|model| |cache|請求緩存|cache| |param_depr|路由參數分隔符|depr| |ajax|Ajax檢測|ajax| |pjax|Pjax檢測|pjax| |response|綁定response_send行為|response| |validate|綁定驗證器類進行數據驗證|validate| |header|設置Response的header信息|header| |append|追加額外的參數（`5.1.5+`）|append| |middleware|注冊路由中間件（`5.1.6+`）|middleware| |merge_rule_regex|合并路由規則（`V5.1.6+`）|mergeRuleRegex| |filter|請求變量過濾（`V5.1.16+`）|filter| >[danger] `ext`和`deny_ext`參數允許設置為空，分別表示不允許任何后綴以及必須使用后綴訪問。 >[info] `V5.1.6+`版本開始，路由的`before`行為參數建議改為使用路由中間件替代。用法舉例： ~~~ Route::get('new/:id','News/read',['ext'=>'html','https'=>true]); ~~~ 和使用方法設置（新版推薦的設置方式）等效 ~~~ Route::get('new/:id', 'News/read') ->ext('html') ->https(); ~~~ 顯然第二種方式更加直觀，而且便于IDE的自動提示。 > 這些路由參數可以混合使用，只要有任何一條參數檢查不通過，當前路由就不會生效，繼續檢測后面的路由規則。 ### URL后綴 >[danger] URL后綴如果是全局統一的話，可以在應用配置文件`app.php`中設置`url_html_suffix`參數，如果當前訪問的URL地址中的URL后綴是允許的偽靜態后綴，那么后綴本身是不會被作為參數值傳入的。不同參數設置的區別如下：配置值|描述 ---|---|--- `false`|禁止偽靜態訪問空字符串|允許任意偽靜態后綴 `html`|只允許設置的偽靜態后綴 ~~~ // 定義GET請求路由規則并設置URL后綴為html的時候有效 Route::get('new/:id', 'News/read') ->ext('html'); ~~~ 支持匹配多個后綴，例如： ~~~php Route::get('new/:id', 'News/read') ->ext('shtml|html'); ~~~ > 如果`ext`方法不傳入任何值，表示不允許使用任何后綴訪問。可以設置禁止訪問的URL后綴，例如： ~~~ // 定義GET請求路由規則并設置禁止URL后綴為png、jpg和gif的訪問 Route::get('new/:id', 'News/read') ->denyExt('jpg|png|gif'); ~~~ > 如果`denyExt`方法不傳入任何值，表示必須使用后綴訪問。 ### 域名檢測支持使用完整域名或者子域名進行檢測，例如： ~~~ // 完整域名檢測只在news.thinkphp.cn訪問時路由有效 Route::get('new/:id', 'News/read') ->domain('news.thinkphp.cn'); // 子域名檢測 Route::get('new/:id', 'News/read') ->domain('news'); ~~~ > 如果需要給子域名定義批量的路由規則，建議使用`domain`方法進行路由定義。 ### HTTPS檢測支持檢測當前是否HTTPS訪問 ~~~ // 必須使用HTTPS訪問 Route::get('new/:id', 'News/read') ->https(); // 必須使用HTTP訪問 Route::get('new/:id', 'News/read') ->https(false); ~~~ ### 請求變量檢測（`V5.1.16+`）可以在匹配URL地址之外，額外檢查請求變量是否匹配，只有指定的請求變量也一致的情況下才能匹配該路由。 ~~~ // 檢查type變量 Route::post('new/:id', 'News/save') ->filter('type', 1); // 檢查多個請求變量 Route::post('new/:id', 'News/save') ->filter([ 'type' => 1,'status'=> 1 ]); ~~~ ### 前置行為檢測支持使用行為對路由進行檢測是否匹配，如果行為方法返回`false`表示當前路由規則無效。 ~~~ Route::get('user/:id', 'index/User/read') ->before(['\app\index\behavior\UserCheck']); ~~~ 行為類定義如下： ~~~ <?php namespace app\index\behavior; class UserCheck { public function run() { if ('user/0' == request()->url()) { return false; } } } ~~~ 可以同時使用多個行為進行檢測，并且支持使用閉包。 >[danger] 因為前置行為的特殊性，在路由參數的有效性檢查后，無論是否最終匹配該路由，都會進行前置行為檢查（路由分組的話會在匹配該分組后再檢查）。 ### 后置行為執行 >[danger] `V5.1.6+`版本開始建議使用中間件替代路由后置行為。可以為某個路由或者某個分組路由定義后置行為執行，表示當路由匹配成功后，執行的行為，例如： ~~~ Route::get('user/:id', 'User/read') ->after(['\app\index\behavior\ReadInfo']); ~~~ 其中`ReadInfo`行為類定義如下： ~~~ <?php namespace app\index\behavior; use app\index\model\User; class ReadInfo { public function run() { $id = request()->route('id'); app()->user = User::get($id); } } ~~~ 如果成功匹配到`new/:id`路由后，就會執行行為類的`run`方法，參數是路由地址，可以動態改變。同樣，后置行為也支持傳入閉包。 ### 合并額外參數通常用于完整匹配的情況，如果有額外的參數則合并作為變量值，例如： ~~~ Route::get('new/:name$', 'News/read') ->mergeExtraVars(); ~~~ ~~~ http://serverName/new/thinkphp/hello ~~~ 會被匹配到，并且`name`變量的值為 `thinkphp/hello`。 ### 路由綁定模型路由規則和分組支持綁定模型數據，例如： ~~~php Route::get('hello/:id', 'index/index/hello') ->model('id', '\app\index\model\User'); ~~~ 會自動給當前路由綁定 `id`為當前路由變量值的`User`模型數據。如果你的模型綁定使用的是`id`作為查詢條件的話，還可以簡化成下面的方式 ~~~php Route::get('hello/:id', 'index/index/hello') ->model('\app\index\model\User'); ~~~ 默認情況下，如果沒有查詢到模型數據，則會拋出異常，如果不希望拋出異常，可以使用 ~~~php Route::rule('hello/:id', 'index/index/hello') ->model('id', '\app\index\model\User', false); ~~~ 可以定義模型數據的查詢條件，例如： ~~~ Route::rule('hello/:name/:id', 'index/index/hello') ->model('id&name', '\app\index\model\User'); ~~~ 表示查詢`id`和`name`的值等于當前路由變量的模型數據。也可以使用閉包來自定義返回需要的模型對象 ~~~ Route::rule('hello/:id', 'index/index/hello') ->model(function ($id) { $model = new \app\index\model\User; return $model->where('id', $id)->find(); }); ~~~ 閉包函數的參數就是當前請求的URL變量信息。 > 綁定的模型可以直接在控制器的架構方法或者操作方法中自動注入，具體可以參考請求章節的依賴注入。 ### 緩存路由請求可以對當前的路由請求進行緩存處理，例如： ~~~ Route::get('new/:name$', 'News/read') ->cache(3600); ~~~ 表示對當前路由請求緩存3600秒，更多內容可以參考[請求緩存](353992)一節。 ## 設置Header信息 ~~~ Route::get('new/:name$', 'News/read') ->header('Access-Control-Allow-Origin','*'); ~~~ > header方法支持多次調用。或者使用數組方式批量設置 ~~~ Route::get('new/:name$', 'News/read') ->header([ 'Access-Control-Allow-Origin'=>'*', 'Access-Control-Allow-Methods' => 'GET, POST, PATCH, PUT, DELETE', ]); ~~~ 當路由匹配后，會自動設置本次請求的Response響應對象的Header信息。 ## 響應輸出設置可以調用`response`方法給路由或者分組綁定響應輸出參數，例如： ~~~ Route::get('hello/:id', 'index/index/hello')->response([ '\app\index\behavior\Json', ]); ~~~ 行為類定義如下： ~~~ namespace app\index\behavior; class Json { public function run($response) { // 調用Response類的方法進行設置 $response->contentType('application/json'); } } ~~~ 如果不希望使用行為，可以直接使用閉包 ~~~ Route::get('hello/:id', 'index/index/hello')->response(function($response){ $response->contentType('application/json'); }); ~~~ 如果要給某個路由返回單獨的響應對象，也可以使用 ~~~ Route::get('hello/:id', function () { return json('hello,world!'); }); ~~~ ## 全局路由參數可以直接進行全局的路由參數設置，例如在路由定義文件中使用 ~~~ Route::option('ext','html')->option('cache', 600); ~~~ 表示全局路由都使用html后綴以及600秒的請求緩存。 ## 動態參數如果你需要額外自定義一些路由參數，可以使用下面的方式： ~~~ Route::get('new/:name$', 'News/read') ->option('rule','admin'); ~~~ 或者使用動態方法 ~~~ Route::get('new/:name$', 'News/read') ->rule('admin'); ~~~ 在后續的路由行為后可以調用該路由的`rule`參數來進行權限檢查。 ## 路由中間件（`V5.1.6+`）從`5.1.6+`版本開始，可以使用路由中間件，注冊方式如下： ~~~ Route::rule('hello/:name','hello') ->middleware('Auth'); ~~~ 或者對路由分組注冊中間件 ~~~ Route::group('hello', function(){ Route::rule('hello/:name','hello'); })->middleware('Auth'); ~~~ 如果需要傳入額外參數給中間件，可以使用 ~~~ Route::rule('hello/:name','hello') ->middleware('Auth:admin'); ~~~ 如果使用的是常量方式定義，可以在第二個參數傳入中間件參數。 ~~~ Route::rule('hello/:name','hello') ->middleware(Auth::class, 'admin'); ~~~ 如果需要定義多個中間件，使用數組方式 ~~~ Route::rule('hello/:name','hello') ->middleware([Auth::class, 'Check']); ~~~ 可以統一傳入同一個額外參數 ~~~ Route::rule('hello/:name','hello') ->middleware([Auth::class, 'Check'], 'admin'); ~~~ 或者單獨指定中間件參數。 ~~~ Route::rule('hello/:name','hello') ->middleware(['Auth:admin', 'Check:editor']); ~~~ 更多中間件的用法參考架構章節的[中間件](中間件.md)內容。