中間件 · laravel 5.3 中文文檔

# HTTP 中間件 - [簡介](#introduction) - [創建中間件](#defining-middleware) - [注冊中間件](#registering-middleware) - [全局中間件](#global-middleware) - [為路由指定中間件](#assigning-middleware-to-routes) - [中間件組](#middleware-groups) - [中間件參數](#middleware-parameters) - [Terminable 中間件](#terminable-middleware) <a name="introduction"></a> ## 簡介 HTTP 中間件提供了一個方便的機制來過濾進入應用程序的 HTTP 請求，例如，Auth 中間件驗證用戶的身份，如果用戶未通過身份驗證，中間件將會把用戶導向登錄頁面，反之，當用戶通過了身份驗證，中間件將會通過此請求并接著往下執行。當然，除了身份驗證之外，中間件也可以被用來運行各式各樣的任務，如：CORS 中間件負責替所有即將離開程序的響應加入適當的標頭；而日志中間件則可以記錄所有傳入應用程序的請求。 Laravel 框架已經內置了一些中間件，包括維護、身份驗證、CSRF 保護，等等。所有的中間件都放在 `app/Http/Middleware` 目錄內。 <a name="defining-middleware"></a> ## 創建中間件要創建一個新的中間件，則可以使用 `make:middleware` 這個 Artisan 命令： php artisan make:middleware CheckAge 此命令將會在 `app/Http/Middleware` 目錄內設定一個名稱為 `CheckAge` 的類。在這個中間件內我們只允許請求的年齡 `age` 變量大于 200 時才能訪問路由，否則，我們會將用戶重定向到首頁「home」這個 URI 上。 <?php namespace App\Http\Middleware; use Closure; class CheckAge { /** * 運行請求過濾器。 * * @param \Illuminate\Http\Request $request * @param \Closure $next * @return mixed */ public function handle($request, Closure $next) { if ($request->age <= 200) { return redirect('home'); } return $next($request); } } 如你所見，若是 age 小于 200，中間件將會返回 HTTP 重定向給用戶端，否則，請求將會進一步傳遞到應用程序。只需調用帶有 `$request` 的 `$next` 方法，即可將請求傳遞到更深層的應用程序（相當于允許通過中間件）。 HTTP 請求在實際碰觸到應用程序之前，最好是可以層層通過中間件。每一層都可以對請求進行檢查，甚至完全拒絕請求。 ### 前置中間件 / 后置中間件「前置中間件（BeforeMiddleware）」運行于請求處理之前： <?php namespace App\Http\Middleware; use Closure; class BeforeMiddleware { public function handle($request, Closure $next) { // Perform action return $next($request); } } > 譯者注：前置中間件運行的時間點是在每一個請求處理之前，可以參閱此文章加深理解：[如何查看 Laravel 5 的所有數據庫請求](https://phphub.org/topics/2018) 這個中間件會在應用程序處理請求 **后** 運行它的任務： <?php namespace App\Http\Middleware; use Closure; class AfterMiddleware { public function handle($request, Closure $next) { $response = $next($request); // Perform action return $response; } } <a name="registering-middleware"></a> ## 注冊中間件 <a name="global-middleware"></a> ### 全局中間件若是希望每個 HTTP 請求都經過一個中間件，只要將中間件的類加入到 `app/Http/Kernel.php` 的 `$middleware` 屬性清單列表中。 <a name="assigning-middleware-to-routes"></a> ### 為路由指派中間件如果你要指派中間件給特定路由，你得先在 `app/Http/Kernel.php` 給中間件設置一個好記的 `鍵`，默認情況下，這個文件內的 `$routeMiddleware` 屬性已包含了 Laravel 目前設置的中間件，你只需要在清單列表中加上一組自定義的鍵即可。 // 在 App\Http\Kernel 類內... protected $routeMiddleware = [ 'auth' => \Illuminate\Auth\Middleware\Authenticate::class, 'auth.basic' => \Illuminate\Auth\Middleware\AuthenticateWithBasicAuth::class, 'bindings' => \Illuminate\Routing\Middleware\SubstituteBindings::class, 'can' => \Illuminate\Auth\Middleware\Authorize::class, 'guest' => \App\Http\Middleware\RedirectIfAuthenticated::class, 'throttle' => \Illuminate\Routing\Middleware\ThrottleRequests::class, ]; 中間件一旦在 HTTP `kernel` 文件內被定義，即可在路由選項內使用 `middleware` 鍵值指定： Route::get('admin/profile', function () { // })->middleware('auth'); 為路由指定多個中間件： Route::get('/', function () { // })->middleware('first', 'second'); 你可以使用完整類名作為路由指派中間件。 use App\Http\Middleware\CheckAge; Route::get('admin/profile', function () { // })->middleware(CheckAge::class); <a name="middleware-groups"></a> ### 中間件組有時候你可能想要通過指定一個鍵名的方式將相關中間件分到一個組里面，從而更方便將其分配到路由中，這可以通過使用 HTTP Kernel 的 `$middlewareGroups` 實現。 Laravel 自帶了開箱即用的 `web` 和 `api` 兩個中間件組以包含可以應用到 Web UI 和 API 路由的通用中間件： /** * 應用程序的中間件組 * * @var array */ protected $middlewareGroups = [ 'web' => [ \App\Http\Middleware\EncryptCookies::class, \Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class, \Illuminate\Session\Middleware\StartSession::class, \Illuminate\View\Middleware\ShareErrorsFromSession::class, \App\Http\Middleware\VerifyCsrfToken::class, \Illuminate\Routing\Middleware\SubstituteBindings::class, ], 'api' => [ 'throttle:60,1', 'auth:api', ], ]; 中間件組可以被分配給路由和控制器動作，使用和單個中間件分配同樣的語法。再次申明，中間件組的目的只是讓一次分配給路由多個中間件的實現更加簡單： Route::get('/', function () { // })->middleware('web'); Route::group(['middleware' => ['web']], function () { // }); > {tip} 默認情況下，`RouteServiceProvider` 已經為 `routes.php` 文件指定了 `web` 中間件組。 <a name="middleware-parameters"></a> ## 中間件參數中間件也可以接收自定義傳參，例如，要在運行特定操作前檢查已驗證用戶是否具備該操作的「角色」，可以創建 `RoleMiddleware` 來接收角色名稱作為額外的傳參。附加的中間件參數將會在 `$next` 參數之后被傳入中間件： <?php namespace App\Http\Middleware; use Closure; class CheckRole { /** * 運行請求過濾 * * @param \Illuminate\Http\Request $request * @param \Closure $next * @param string $role * @return mixed */ public function handle($request, Closure $next, $role) { if (! $request->user()->hasRole($role)) { // 重定向... } return $next($request); } } 在路由中可使用冒號 `:` 來區隔中間件名稱與指派參數，多個參數可使用逗號作為分隔： Route::put('post/{id}', function ($id) { // })->middleware('role:editor'); <a name="terminable-middleware"></a> ## Terminable 中間件有些時候中間件需要在 HTTP 響應被發送到瀏覽器之后才運行，例如，Laravel 內置的「session」中間件存儲的 session 數據是在響應被發送到瀏覽器之后才進行寫入的。想要做到這一點，你需要定義中間件為「terminable」。 <?php namespace Illuminate\Session\Middleware; use Closure; class StartSession { public function handle($request, Closure $next) { return $next($request); } public function terminate($request, $response) { // 保存 session 數據... } } `terminate` 方法必須接收請求及響應。一旦定義了 terminable 中間件，你便需要將它增加到 HTTP kernel 文件的全局中間件清單列表中。當在你的中間件調用 `terminate` 方法時，Laravel 會從 [服務容器](/docs/{{version}}/container) 解析一個全新的中間件實例。如果你希望在 `handle` 及 `terminate` 方法被調用時使用一致的中間件實例，只需在容器中使用容器的 `singleton` 方法注冊中間件。