中介軟體 - Middleware

• 簡介
• 定義 Middleware
• 註冊 Middleware
  • 全域 Middleware
  • 將 Middleware 指派給 Route
  • Middleware 群組
  • 排序 Middleware
• Middleware 參數
• 可終止的 Middleware

簡介

Middleware 提供了一個機制，可檢驗與過濾進入應用程式的 HTTP Request。舉例來說，Laravel 中包含了一個可以認證使用者是否已登入的 Middleware。若使用者未登入，該 Middleware 會將使用者重新導向回登入畫面。不過，若使用者已登入，這個 Middleware 就會讓 Request 進一步進入程式中處理。

除了登入認證外，我們還能撰寫追加的 Middleware 來進行各種任務。舉例來說，可以有個 Logging Middleware 來將程式的所有連入 Request 都紀錄到日誌裡。Laravel Framework 還包含了許多 Middleware，包含用於登入認證的 Middleware、以及用於 CSRF 保護的 Middleware。這些 Middleware 都放置在 app/Http/Middleware 目錄內。

定義 Middleware

若要建立新的 Middleware，請使用 make:middleware Artisan 指令：

1php artisan make:middleware EnsureTokenIsValid
1php artisan make:middleware EnsureTokenIsValid

該指令會在 app/Http/Middleware 目錄中放置一個新的 EnsureTokenIsValid 類別。在這個 Middleware 中，我們要只在提供的 token 符合特定的值時才允許存取該 Route。token 不符合時，會將使用者重新導向回到 home URI：

 1<?php
 2 
 3namespace App\Http\Middleware;
 4 
 5use Closure;
 6 
 7class EnsureTokenIsValid
 8{
 9    /**
10     * Handle an incoming request.
11     *
12     * @param  \Illuminate\Http\Request  $request
13     * @param  \Closure  $next
14     * @return mixed
15     */
16    public function handle($request, Closure $next)
17    {
18        if ($request->input('token') !== 'my-secret-token') {
19            return redirect('home');
20        }
21 
22        return $next($request);
23    }
24}
 1<?php
 2 
 3namespace App\Http\Middleware;
 4 
 5use Closure;
 6 
 7class EnsureTokenIsValid
 8{
 9    /**
10     * Handle an incoming request.
11     *
12     * @param  \Illuminate\Http\Request  $request
13     * @param  \Closure  $next
14     * @return mixed
15     */
16    public function handle($request, Closure $next)
17    {
18        if ($request->input('token') !== 'my-secret-token') {
19            return redirect('home');
20        }
21 
22        return $next($request);
23    }
24}

就像我們可以看到的一樣，若給定的 token 不符合我們的私密權杖 (Secret Token)，則這個 Middleware 會回傳一個 HTTP Redirect 給用戶端。token 符合時，這個 Request 就會進一步地傳給我們的程式。若要將 Request 進一步傳進我們的應用程式中 (即，讓 Middleware「通過 - Pass」)，應以 $request 呼叫 $next 回呼。

最好想像成我們有「一層又一層」的 Middleware。HTTP Request 必須通過每一層的 Middleware，最後才能進入你的應用程式中。每一層 Middleware 都可以檢查 Request 的內容，甚至還能完全拒絕 Request。

Middleare 與 Response

當然，Middleware 可以在將 Request 傳入應用程式的前後執行。舉例來說，下列 Middleware 會在 Request 被程式處理 之後 進行一些任務：

 1<?php
 2 
 3namespace App\Http\Middleware;
 4 
 5use Closure;
 6 
 7class BeforeMiddleware
 8{
 9    public function handle($request, Closure $next)
10    {
11        // Perform action
12 
13        return $next($request);
14    }
15}
 1<?php
 2 
 3namespace App\Http\Middleware;
 4 
 5use Closure;
 6 
 7class BeforeMiddleware
 8{
 9    public function handle($request, Closure $next)
10    {
11        // Perform action
12 
13        return $next($request);
14    }
15}

不過，這個 Middleware 會在 Request 被程式處理 之後 才進行其任務：

 1<?php
 2 
 3namespace App\Http\Middleware;
 4 
 5use Closure;
 6 
 7class AfterMiddleware
 8{
 9    public function handle($request, Closure $next)
10    {
11        $response = $next($request);
12 
13        // Perform action
14 
15        return $response;
16    }
17}
 1<?php
 2 
 3namespace App\Http\Middleware;
 4 
 5use Closure;
 6 
 7class AfterMiddleware
 8{
 9    public function handle($request, Closure $next)
10    {
11        $response = $next($request);
12 
13        // Perform action
14 
15        return $response;
16    }
17}

註冊 Middleware

全域 Middleware

若想讓 Middleware 在每一個 HTTP Request 上都執行的話，請將該 Middleware 列在 app/Http/Kernel.php 類別中的 $middleware 屬性內。

將 Middleware 指派給 Route

若想將 Middleware 指派給特定的 Route，請先在專案的 app/Http/Kernel.php 檔案中為該 Middleware 指派一個索引鍵。預設情況下，這個類別的 $routeMiddleware 屬性包含了 Laravel 附帶的 Middleware。我們可以在這個列表中列出我們自己的 Middleware，並為其指派一個自訂的索引鍵：

 1// 在 App\Http\Kernel 類別中...
 2 
 3protected $routeMiddleware = [
 4    'auth' => \App\Http\Middleware\Authenticate::class,
 5    'auth.basic' => \Illuminate\Auth\Middleware\AuthenticateWithBasicAuth::class,
 6    'bindings' => \Illuminate\Routing\Middleware\SubstituteBindings::class,
 7    'cache.headers' => \Illuminate\Http\Middleware\SetCacheHeaders::class,
 8    'can' => \Illuminate\Auth\Middleware\Authorize::class,
 9    'guest' => \App\Http\Middleware\RedirectIfAuthenticated::class,
10    'signed' => \Illuminate\Routing\Middleware\ValidateSignature::class,
11    'throttle' => \Illuminate\Routing\Middleware\ThrottleRequests::class,
12    'verified' => \Illuminate\Auth\Middleware\EnsureEmailIsVerified::class,
13];
 1// 在 App\Http\Kernel 類別中...
 2 
 3protected $routeMiddleware = [
 4    'auth' => \App\Http\Middleware\Authenticate::class,
 5    'auth.basic' => \Illuminate\Auth\Middleware\AuthenticateWithBasicAuth::class,
 6    'bindings' => \Illuminate\Routing\Middleware\SubstituteBindings::class,
 7    'cache.headers' => \Illuminate\Http\Middleware\SetCacheHeaders::class,
 8    'can' => \Illuminate\Auth\Middleware\Authorize::class,
 9    'guest' => \App\Http\Middleware\RedirectIfAuthenticated::class,
10    'signed' => \Illuminate\Routing\Middleware\ValidateSignature::class,
11    'throttle' => \Illuminate\Routing\Middleware\ThrottleRequests::class,
12    'verified' => \Illuminate\Auth\Middleware\EnsureEmailIsVerified::class,
13];

Middleware 被定義為 HTTP Kernel 後，就可以使用 middleware 方法來將 Middleware 指派給 Route：

1Route::get('/profile', function () {
2    //
3})->middleware('auth');
1Route::get('/profile', function () {
2    //
3})->middleware('auth');

也可以傳入一組 Middleware 陣列給 middleware 方法來指派多個 Middleware 給 Route：

1Route::get('/', function () {
2    //
3})->middleware(['first', 'second']);
1Route::get('/', function () {
2    //
3})->middleware(['first', 'second']);

指派 Middleware 時，也可以傳入完整類別名稱 (Fully Qualified Class Name)：

1use App\Http\Middleware\EnsureTokenIsValid;
2 
3Route::get('/profile', function () {
4    //
5})->middleware(EnsureTokenIsValid::class);
1use App\Http\Middleware\EnsureTokenIsValid;
2 
3Route::get('/profile', function () {
4    //
5})->middleware(EnsureTokenIsValid::class);

排除 Middleware

當我們將 Middleware 指派給 Route 群組時，我們有時候會需要讓某個 Middleware 不要被套用到群組中的個別 Route 上。我們可以使用 withoutMiddleware 方法來完成：

 1use App\Http\Middleware\EnsureTokenIsValid;
 2 
 3Route::middleware([EnsureTokenIsValid::class])->group(function () {
 4    Route::get('/', function () {
 5        //
 6    });
 7 
 8    Route::get('/profile', function () {
 9        //
10    })->withoutMiddleware([EnsureTokenIsValid::class]);
11});
 1use App\Http\Middleware\EnsureTokenIsValid;
 2 
 3Route::middleware([EnsureTokenIsValid::class])->group(function () {
 4    Route::get('/', function () {
 5        //
 6    });
 7 
 8    Route::get('/profile', function () {
 9        //
10    })->withoutMiddleware([EnsureTokenIsValid::class]);
11});

也可以將一組 Middleware 從整個 Route 群組定義中排除：

1use App\Http\Middleware\EnsureTokenIsValid;
2 
3Route::withoutMiddleware([EnsureTokenIsValid::class])->group(function () {
4    Route::get('/profile', function () {
5        //
6    });
7});
1use App\Http\Middleware\EnsureTokenIsValid;
2 
3Route::withoutMiddleware([EnsureTokenIsValid::class])->group(function () {
4    Route::get('/profile', function () {
5        //
6    });
7});

withoutMiddleware 方法只能移除 Route Middleware，不能移除全域 Middleware。

Middleware 群組

有時候，我們會想將多個 Middleware 分組在單一索引鍵上，來讓我們可以輕鬆地將其指派給 Route。可以在 HTTP Kernel 中使用 $middlewareGroups 屬性來完成。

Laravel 中安裝完後就自帶了 web 與 api 兩個 Middleware 群組，其中共包含了可用在網頁與 API Route 上的常見 Middleware。請記得，這些 Middleware 群組由 App\Providers\RouteServiceProvider Service Provider 自動套用到對應的 web 與 api Route 檔案：

 1/**
 2 * The application's route middleware groups.
 3 *
 4 * @var array
 5 */
 6protected $middlewareGroups = [
 7    'web' => [
 8        \App\Http\Middleware\EncryptCookies::class,
 9        \Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class,
10        \Illuminate\Session\Middleware\StartSession::class,
11        // \Illuminate\Session\Middleware\AuthenticateSession::class,
12        \Illuminate\View\Middleware\ShareErrorsFromSession::class,
13        \App\Http\Middleware\VerifyCsrfToken::class,
14        \Illuminate\Routing\Middleware\SubstituteBindings::class,
15    ],
16 
17    'api' => [
18        'throttle:api',
19        \Illuminate\Routing\Middleware\SubstituteBindings::class,
20    ],
21];
 1/**
 2 * The application's route middleware groups.
 3 *
 4 * @var array
 5 */
 6protected $middlewareGroups = [
 7    'web' => [
 8        \App\Http\Middleware\EncryptCookies::class,
 9        \Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class,
10        \Illuminate\Session\Middleware\StartSession::class,
11        // \Illuminate\Session\Middleware\AuthenticateSession::class,
12        \Illuminate\View\Middleware\ShareErrorsFromSession::class,
13        \App\Http\Middleware\VerifyCsrfToken::class,
14        \Illuminate\Routing\Middleware\SubstituteBindings::class,
15    ],
16 
17    'api' => [
18        'throttle:api',
19        \Illuminate\Routing\Middleware\SubstituteBindings::class,
20    ],
21];

也可以使用相同的語法來將 Middleware 群組作為個別 Middleware 一樣指派給 Route 與 Controller 動作。同樣的，使用 Middleware 群組來一次指派多個 Middleware 給 Route 比較方便：

1Route::get('/', function () {
2    //
3})->middleware('web');
4 
5Route::middleware(['web'])->group(function () {
6    //
7});
1Route::get('/', function () {
2    //
3})->middleware('web');
4 
5Route::middleware(['web'])->group(function () {
6    //
7});

排序 Middleware

我們偶爾會需要讓 Middleware 以特定的順序執行，但有時候沒有辦法控制 Middleware 是以什麼順序指派給 Route 的。這時，我們可以使用 app/Http/Kernel.php 檔案中的 $middlewarePriority 屬性來執行 Middleware 的優先順序。這個屬性預設可能不存在 HTTP Kernel 中。若沒有這個屬性，可以複製下列預設定義來用：

 1/**
 2 * The priority-sorted list of middleware.
 3 *
 4 * This forces non-global middleware to always be in the given order.
 5 *
 6 * @var string[]
 7 */
 8protected $middlewarePriority = [
 9    \Illuminate\Cookie\Middleware\EncryptCookies::class,
10    \Illuminate\Session\Middleware\StartSession::class,
11    \Illuminate\View\Middleware\ShareErrorsFromSession::class,
12    \Illuminate\Contracts\Auth\Middleware\AuthenticatesRequests::class,
13    \Illuminate\Routing\Middleware\ThrottleRequests::class,
14    \Illuminate\Routing\Middleware\ThrottleRequestsWithRedis::class,
15    \Illuminate\Session\Middleware\AuthenticateSession::class,
16    \Illuminate\Routing\Middleware\SubstituteBindings::class,
17    \Illuminate\Auth\Middleware\Authorize::class,
18];
 1/**
 2 * The priority-sorted list of middleware.
 3 *
 4 * This forces non-global middleware to always be in the given order.
 5 *
 6 * @var string[]
 7 */
 8protected $middlewarePriority = [
 9    \Illuminate\Cookie\Middleware\EncryptCookies::class,
10    \Illuminate\Session\Middleware\StartSession::class,
11    \Illuminate\View\Middleware\ShareErrorsFromSession::class,
12    \Illuminate\Contracts\Auth\Middleware\AuthenticatesRequests::class,
13    \Illuminate\Routing\Middleware\ThrottleRequests::class,
14    \Illuminate\Routing\Middleware\ThrottleRequestsWithRedis::class,
15    \Illuminate\Session\Middleware\AuthenticateSession::class,
16    \Illuminate\Routing\Middleware\SubstituteBindings::class,
17    \Illuminate\Auth\Middleware\Authorize::class,
18];

Middleware 參數

Middleware 也可以接收額外的參數。舉例來說，若你的程式需要在執行給定動作前認證登入的使用者是否有給定的「職位 (Role)」，則我們可以先建立一個 EnsureUserHasRole Middleware，讓該 Middleware 接收一個職位名稱來作為其額外的引數。

額外的 Middleware 引數會被放在 $next 引數之後傳遞給 Middleware：

 1<?php
 2 
 3namespace App\Http\Middleware;
 4 
 5use Closure;
 6 
 7class EnsureUserHasRole
 8{
 9    /**
10     * Handle the incoming request.
11     *
12     * @param  \Illuminate\Http\Request  $request
13     * @param  \Closure  $next
14     * @param  string  $role
15     * @return mixed
16     */
17    public function handle($request, Closure $next, $role)
18    {
19        if (! $request->user()->hasRole($role)) {
20            // Redirect...
21        }
22 
23        return $next($request);
24    }
25 
26}
 1<?php
 2 
 3namespace App\Http\Middleware;
 4 
 5use Closure;
 6 
 7class EnsureUserHasRole
 8{
 9    /**
10     * Handle the incoming request.
11     *
12     * @param  \Illuminate\Http\Request  $request
13     * @param  \Closure  $next
14     * @param  string  $role
15     * @return mixed
16     */
17    public function handle($request, Closure $next, $role)
18    {
19        if (! $request->user()->hasRole($role)) {
20            // Redirect...
21        }
22 
23        return $next($request);
24    }
25 
26}

也可以在定義 Route 時使用 : 區分出 Middleware 名稱與參數來指定 Middleware 參數。多個參數請使用逗點 (,) 區隔：

1Route::put('/post/{id}', function ($id) {
2    //
3})->middleware('role:editor');
1Route::put('/post/{id}', function ($id) {
2    //
3})->middleware('role:editor');

可終止的 Middleware

有時候，某個 Middleware 可能需要在 HTTP Response 被傳送到瀏覽器後才進行某些動作。若我們在 Middleware 上定義一個 terminate 方法，且網頁伺服器 (Web Server) 使用 FastCGI，則會在 Response 傳送給瀏覽器後會自動呼叫 terminate 方法：

 1<?php
 2 
 3namespace Illuminate\Session\Middleware;
 4 
 5use Closure;
 6 
 7class TerminatingMiddleware
 8{
 9    /**
10     * Handle an incoming request.
11     *
12     * @param  \Illuminate\Http\Request  $request
13     * @param  \Closure  $next
14     * @return mixed
15     */
16    public function handle($request, Closure $next)
17    {
18        return $next($request);
19    }
20 
21    /**
22     * Handle tasks after the response has been sent to the browser.
23     *
24     * @param  \Illuminate\Http\Request  $request
25     * @param  \Illuminate\Http\Response  $response
26     * @return void
27     */
28    public function terminate($request, $response)
29    {
30        // ...
31    }
32}
 1<?php
 2 
 3namespace Illuminate\Session\Middleware;
 4 
 5use Closure;
 6 
 7class TerminatingMiddleware
 8{
 9    /**
10     * Handle an incoming request.
11     *
12     * @param  \Illuminate\Http\Request  $request
13     * @param  \Closure  $next
14     * @return mixed
15     */
16    public function handle($request, Closure $next)
17    {
18        return $next($request);
19    }
20 
21    /**
22     * Handle tasks after the response has been sent to the browser.
23     *
24     * @param  \Illuminate\Http\Request  $request
25     * @param  \Illuminate\Http\Response  $response
26     * @return void
27     */
28    public function terminate($request, $response)
29    {
30        // ...
31    }
32}

terminate 方法應接收 Request 與 Response。定義好可終止的 Middleware (Terminable Middleware) 後，請將其加到 Route 列表或 app/Http/Kernel.php 檔案中的全域 Middleware 內。

呼叫 Middleware 上的 terminate 方法時，Laravel 會從 [Service Container] 中解析出這個 Middleware 的新實體。若想讓 handle 與 terminate 都在同一個 Middleware 實體上呼叫的話，請使用 Container 的 singleton 方法來想 Container 註冊這個 Middleware。一般來說，這個註冊應在 AppServiceProvider 的 register 方法中進行：

 1use App\Http\Middleware\TerminatingMiddleware;
 2 
 3/**
 4 * Register any application services.
 5 *
 6 * @return void
 7 */
 8public function register()
 9{
10    $this->app->singleton(TerminatingMiddleware::class);
11}
 1use App\Http\Middleware\TerminatingMiddleware;
 2 
 3/**
 4 * Register any application services.
 5 *
 6 * @return void
 7 */
 8public function register()
 9{
10    $this->app->singleton(TerminatingMiddleware::class);
11}