路由 · laravel 5.4

<article><h1>Laravel HTTP 路由功能</h1><ul><li><a href="#basic-routing">基本路由</a></li><li><a href="#route-parameters">路由參數</a><ul><li><a href="#required-parameters">必選路由參數</a></li><li><a href="#parameters-optional-parameters">可選路由參數</a></li><li><a href="#parameters-regular-expression-constraints">正則表達式約束</a></li></ul></li><li><a href="#named-routes">命名路由</a></li><li><a href="#route-groups">路由組</a><ul><li><a href="#route-group-middleware">中間件</a></li><li><a href="#route-group-namespaces">命名空間</a></li><li><a href="#route-group-sub-domain-routing">子域名路由</a></li><li><a href="#route-group-prefixes">路由前綴</a></li></ul></li><li><a href="#route-model-binding">路由模型綁定</a><ul><li><a href="#implicit-binding">隱式綁定</a></li><li><a href="#explicit-binding">顯式綁定</a></li></ul></li><li><a href="#form-method-spoofing">表單方法偽造</a></li><li><a href="#accessing-the-current-route">獲取當前路由信息</a></li></ul><a name="basic-routing"></a><h2><a href="#basic-routing">基本路由</a></h2>構建最基本的路由只需要一個 URI 與一個 <code class=" language-php">閉包</code>，這里提供了一個非常簡單優雅的定義路由的方法：<pre class=" language-php"><code class=" language-php">Route::get('foo', function () { return 'Hello World'; });</code></pre><h4>默認路由文件</h4>所有的 Laravel 路由都在 <code class=" language-php">routes</code> 目錄中的路由文件中定義，這些文件都由框架自動加載。在 <code class=" language-php">routes/web.php</code> 文件中定義你的 web 頁面路由。這些路由都會應用 <code class=" language-php">web</code> 中間件組，其提供了諸如 <code class=" language-php">Session</code> 和 <code class=" language-php">CSRF</code> 保護等特性。定義在 <code class=" language-php">routes/api.php</code> 中的路由都是無狀態的，并且會應用 <code class=" language-php">api</code> 中間件組。大多數的應用構建，都是以在 <code class=" language-php">routes/web.php</code> 文件定義路由開始的。<h4>可用的路由方法</h4>我們可以注冊路由來響應所有的 HTTP 操作：<pre class=" language-php"><code class=" language-php">Route::get($uri, $callback); Route::post($uri, $callback); Route::put($uri, $callback); Route::patch($uri, $callback); Route::delete($uri, $callback); Route::options($uri, $callback);</code></pre>有的時候你可能需要注冊一個可響應多個 HTTP 方法的路由，這時你可以使用 <code class=" language-php">match</code> 方法，也可以使用 <code class=" language-php">any</code> 方法注冊一個實現響應所有 HTTP 的請求的路由：<pre class=" language-php"><code class=" language-php">Route::match(['get', 'post'], '/', function () { // }); Route::any('foo', function () { // });</code></pre><h4>CSRF 保護</h4>任何指向 <code class=" language-php">web</code> 中 <code class=" language-php">POST</code>, <code class=" language-php">PUT</code> 或 <code class=" language-php">DELETE</code> 路由的 HTML 表單請求都應該包含一個 CSRF 令牌，否則，這個請求將會被拒絕。更多的關于 CSRF 的說明在 <a href="/docs/5.4/csrf">CSRF 說明文檔</a>：<pre class=" language-php"><code class=" language-php"><form method="POST" action="/profile"> {{ csrf_field() }} ... </form></code></pre><a name="route-parameters"></a><h2><a href="#route-parameters">路由參數</a></h2><a name="required-parameters"></a><h3>必選路由參數</h3>當然，有時我們需要在路由中捕獲一些 URL 片段。例如，我們需要從 URL 中捕獲用戶的 ID ，我們可以這樣定義路由參數：<pre class=" language-php"><code class=" language-php">Route::get('user/{id}', function ($id) { return 'User '.$id; });</code></pre>也可以根據需要在路由中定義多個參數：<pre class=" language-php"><code class=" language-php">Route::get('posts/{post}/comments/{comment}', function ($postId, $commentId) { // });</code></pre>路由的參數通常都會被放在 <code class=" language-php">{}</code> 內，并且參數名只能為字母，當運行路由時，參數會通過路由閉包來傳遞。<blockquote>注意： 路由參數不能包含 <code class=" language-php">-</code> 字符。請用下劃線 (<code class=" language-php">_</code>) 替換。</blockquote><a name="parameters-optional-parameters"></a><h3>可選路由參數</h3>聲明路由參數時，如需指定該參數為可選，可以在參數后面加上 <code class=" language-php">?</code> 來實現，但是相應的變量必須有默認值：<pre class=" language-php"><code class=" language-php">Route::get('user/{name?}', function ($name = null) { return $name; }); Route::get('user/{name?}', function ($name = 'John') { return $name; });</code></pre><a name="parameters-regular-expression-constraints"></a><h3>正則表達式約束</h3>你可以使用 <code class=" language-php">where</code> 方法來規范你的路由參數格式。<code class=" language-php">where</code> 方法接受參數名稱和定義參數約束規則的正則表達式：<pre class=" language-php"><code class=" language-php">Route::get('user/{name}', function ($name) { // })->where('name', '[A-Za-z]+'); Route::get('user/{id}', function ($id) { // })->where('id', '[0-9]+'); Route::get('user/{id}/{name}', function ($id, $name) { // })->where(['id' => '[0-9]+', 'name' => '[a-z]+']);</code></pre><a name="parameters-global-constraints"></a><h4>全局約束</h4>如果你希望路由參數在全局范圍內都遵循一個確定的正則表達式約束，則可以使用 <code class=" language-php">pattern</code> 方法。你應該在 <code class=" language-php">RouteServiceProvider</code> 的 <code class=" language-php">boot</code> 方法里定義這些模式：<pre class=" language-php"><code class=" language-php">/** * 定義你的路由模型綁定, pattern 過濾器等。 * * @return void */ public function boot() { Route::pattern('id', '[0-9]+'); parent::boot(); }</code></pre>Pattern 一旦被定義，便會自動應用到所有使用該參數名稱的路由上：<pre class=" language-php"><code class=" language-php">Route::get('user/{id}', function ($id) { // 僅在 {id} 為數字時執行... });</code></pre><a name="named-routes"></a><h2><a href="#named-routes">命名路由</a></h2>命名路由可以方便的生成 <code class=" language-php">URL</code> 或者重定向，你可以在定義路由后使用 <code class=" language-php">name</code> 方法實現：<pre class=" language-php"><code class=" language-php">Route::get('user/profile', function () { // })->name('profile');</code></pre>你還可以為控制器方法指定路由名稱：<pre class=" language-php"><code class=" language-php">Route::get('user/profile', 'UserController@showProfile')->name('profile');</code></pre><h4>為命名路由生成 <code class=" language-php">URL</code></h4>為路由指定了名稱后，我們可以使用全局輔助函數 <code class=" language-php">route</code> 來生成 <code class=" language-php">URL</code> 或者重定向到該條路由：<pre class=" language-php"><code class=" language-php">// 生成 URL... $url = route('profile'); // 生成重定向... return redirect()->route('profile');</code></pre>如果是有定義參數的命名路由，可以把參數作為 <code class=" language-php">route</code> 函數的第二個參數傳入，指定的參數將會自動插入到 <code class=" language-php">URL</code> 中對應的位置：<pre class=" language-php"><code class=" language-php">Route::get('user/{id}/profile', function ($id) { // })->name('profile'); $url = route('profile', ['id' => 1]);</code></pre><a name="route-groups"></a><h2><a href="#route-groups">路由組</a></h2>路由組允許共享路由屬性，例如中間件和命名空間等，我們沒有必要為每個路由單獨設置共有屬性，共有屬性會以數組的形式放到 <code class=" language-php">Route::group</code> 方法的第一個參數中。<a name="route-group-middleware"></a><h3>中間件</h3>要給路由組中定義的所有路由分配中間件，可以在路由組中使用 <code class=" language-php">middleware</code> 鍵，中間件將會依照列表內指定的順序運行：<pre class=" language-php"><code class=" language-php">Route::group(['middleware' => 'auth'], function () { Route::get('/', function () { // 使用 `Auth` 中間件 }); Route::get('user/profile', function () { // 使用 `Auth` 中間件 }); });</code></pre><a name="route-group-namespaces"></a><h3>命名空間</h3>另一個常見的例子是，為控制器組指定公共的 <code class=" language-php">PHP</code> 命名空間。這時使用 <code class=" language-php">namespace</code> 參數來指定組內所有控制器的公共命名空間：<pre class=" language-php"><code class=" language-php">Route::group(['namespace' => 'Admin'], function () { // 在 "App\Http\Controllers\Admin" 命名空間下的控制器 });</code></pre>請記住，默認 <code class=" language-php">RouteServiceProvider</code> 會在命名空間組中引入你的路由文件，讓你不用指定完整的 <code class=" language-php">App\Http\Controllers</code> 命名空間前綴就能注冊控制器路由，因此，我們在定義的時候只需要指定命名空間 <code class=" language-php">App\Http\Controllers</code> 以后的部分。<a name="route-group-sub-domain-routing"></a><h3>子域名路由</h3>路由組也可以用作子域名的通配符，子域名可以像 URI 一樣當作路由組的參數，因此允許把捕獲的子域名一部分用于我們的路由或控制器。可以使用路由組屬性的 <code class=" language-php">domain</code> 鍵聲明子域名。<pre class=" language-php"><code class=" language-php">Route::group(['domain' => '{account}.myapp.com'], function () { Route::get('user/{id}', function ($account, $id) { // }); });</code></pre><a name="route-group-prefixes"></a><h3>路由前綴</h3>通過路由組數組屬性中的 <code class=" language-php">prefix</code> 鍵可以給每個路由組中的路由加上指定的 URI 前綴，例如，我們可以給路由組中所有的 URI 加上路由前綴 <code class=" language-php">admin</code> :<pre class=" language-php"><code class=" language-php">Route::group(['prefix' => 'admin'], function () { Route::get('users', function () { // 匹配包含 "/admin/users" 的 URL }); });</code></pre><a name="route-model-binding"></a><h2><a href="#route-model-binding">路由模型綁定</a></h2>當向路由控制器中注入模型 ID 時，我們通常需要查詢這個 ID 對應的模型，Laravel 路由模型綁定提供了一個方便的方法自動將模型注入到我們的路由中，例如，除了注入一個用戶的 ID，你也可以注入與指定 ID 匹配的完整 <code class=" language-php">User</code> 類實例。<a name="implicit-binding"></a><h3>隱式綁定</h3>Laravel 會自動解析定義在路由或控制器方法（方法包含和路由片段匹配的已聲明類型變量）中的 Eloquent 模型，例如：<pre class=" language-php"><code class=" language-php">Route::get('api/users/{user}', function (App\User $user) { return $user->email; });</code></pre>在這個例子中，由于類型聲明了 Eloquent 模型 <code class=" language-php">App\User</code>，對應的變量名 <code class=" language-php">$user</code> 會匹配路由片段中的 <code class=" language-php">{user}</code>，這樣，Laravel 會自動注入與請求 URI 中傳入的 ID 對應的用戶模型實例。如果數據庫中找不到對應的模型實例，將會自動生成產生一個 404 HTTP 響應。<h4>自定義鍵名</h4>如果你想要隱式模型綁定除 <code class=" language-php">id</code> 以外的數據庫字段，你可以重寫 Eloquent 模型類的 <code class=" language-php">getRouteKeyName</code> 方法：<pre class=" language-php"><code class=" language-php">/** * 為路由模型獲取鍵名 * * @return string */ public function getRouteKeyName() { return 'slug'; }</code></pre><a name="explicit-binding"></a><h3>顯式綁定</h3>使用路由的 <code class=" language-php">model</code> 方法來為已有參數聲明 class 。你應該在 <code class=" language-php">RouteServiceProvider</code> 類中的 <code class=" language-php">boot</code> 方法內定義這些顯式綁定：<pre class=" language-php"><code class=" language-php">public function boot() { parent::boot(); Route::model('user', App\User::class); }</code></pre>接著，定義包含 <code class=" language-php">{user}</code> 參數的路由：<pre class=" language-php"><code class=" language-php">Route::get('profile/{user}', function (App\User $user) { // });</code></pre>因為我們已經綁定 <code class=" language-php">{user}</code> 參數至 <code class=" language-php">App\User</code> 模型，所以 <code class=" language-php">User</code> 實例將被注入該路由。舉個例子，一個至 <code class=" language-php">profile/1</code> 的請求會注入 ID 為 1 的 <code class=" language-php">User</code> 實例。<blockquote>注意：如果在數據庫不存在對應 ID 的數據，就會自動拋出一個 404 異常。</blockquote><h4>自定義解析邏輯</h4>如果你想要使用自定義的解析邏輯，需要使用 <code class=" language-php">Route::bind</code> 方法，傳遞到 <code class=" language-php">bind</code> 方法的閉包會獲取到 URI 請求參數中的值，并且返回你想要在該路由中注入的類實例：<pre class=" language-php"><code class=" language-php">public function boot() { parent::boot(); Route::bind('user', function ($value) { return App\User::where('name', $value)->first(); }); }</code></pre><a name="form-method-spoofing"></a><h2><a href="#form-method-spoofing">表單方法偽造</a></h2>HTML 表單沒有支持 <code class=" language-php">PUT</code>、<code class=" language-php">PATCH</code> 或 <code class=" language-php">DELETE</code> 動作。所以在定義要在 HTML 表單中調用的 <code class=" language-php">PUT</code>、<code class=" language-php">PATCH</code> 或 <code class=" language-php">DELETE</code> 路由時，你將需要在表單中增加隱藏的 <code class=" language-php">_method</code> 字段。 <code class=" language-php">_method</code> 字段的值將被作為 HTTP 的請求方法使用：<pre class=" language-php"><code class=" language-php"><form action="/foo/bar" method="POST"> <input type="hidden" name="_method" value="PUT"> <input type="hidden" name="_token" value="{{ csrf_token() }}"> </form></code></pre>你也可以使用輔助函數 <code class=" language-php">method_field</code> 來生成隱藏的輸入字段 <code class=" language-php">_method</code>：<pre class=" language-php"><code class=" language-php">{{ method_field('PUT') }}</code></pre><a name="accessing-the-current-route"></a><h2><a href="#accessing-the-current-route">獲取當前路由信息</a></h2>你可以使用 <code class=" language-php">Route</code> 上的 <code class=" language-php">current</code>, <code class=" language-php">currentRouteName</code>, and <code class=" language-php">currentRouteAction</code> 方法來訪問處理當前輸入請求的路由信息：<pre class=" language-php"><code class=" language-php">$route = Route::current(); $name = Route::currentRouteName(); $action = Route::currentRouteAction();</code></pre>完整的方法列表請參考 <a href="http://laravel.com/api/5.4/Illuminate/Routing/Router.html">Route facade</a> 和 <a href="http://laravel.com/api/5.4/Illuminate/Routing/Route.html">Route 實例</a><h2>譯者署名</h2><table><thead><tr><th>用戶名</th><th>頭像</th><th>職能</th><th>簽名</th></tr></thead><tbody><tr><td><a href="https://github.com/zhouzihanntu">@zhouzihanntu</a></td><td><img class="avatar-66 rm-style" src="https://avatars0.githubusercontent.com/u/14007659?v=3&s=460"></td><td>翻譯</td><td></td></tr></tbody></table></article>