中介層

簡介
定義中介層
註冊中介層
中介層參數
可終止的中介層

簡介

中介層提供了一種方便的機制，用於檢查和過濾進入您應用程式的 HTTP 請求。例如，Laravel 包含一個中介層，用於驗證您的應用程式使用者是否已通過身份驗證。如果使用者未通過身份驗證，中介層會將使用者重新導向到您應用程式的登入畫面。但是，如果使用者已通過身份驗證，中介層將允許請求繼續進入應用程式。

除了身份驗證之外，還可以編寫其他中介層來執行各種任務。例如，日誌中介層可能會記錄所有進入您應用程式的請求。Laravel 包含各種中介層，包括用於身份驗證和 CSRF 保護的中介層；但是，所有使用者定義的中介層通常都位於您應用程式的 app/Http/Middleware 目錄中。

定義中介層

要建立新的中介層，請使用 make:middleware Artisan 命令

1php artisan make:middleware EnsureTokenIsValid

php artisan make:middleware EnsureTokenIsValid

此命令將在您的 app/Http/Middleware 目錄中放置一個新的 EnsureTokenIsValid 類別。在這個中介層中，我們只允許存取路由，前提是提供的 token 輸入與指定的值相符。否則，我們會將使用者重新導向回 /home URI

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

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class EnsureTokenIsValid
{
    /**
     * Handle an incoming request.
     *
     * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
     */
    public function handle(Request $request, Closure $next): Response
    {
        if ($request->input('token') !== 'my-secret-token') {
            return redirect('/home');
        }

        return $next($request);
    }
}

如您所見，如果給定的 token 與我們的密碼令牌不符，中介層將向客戶端返回 HTTP 重定向；否則，請求將進一步傳遞到應用程式中。要將請求更深入地傳遞到應用程式（允許中介層「通過」），您應該使用 $request 呼叫 $next 回調。

最好將中介層想像成一系列 HTTP 請求在到達您的應用程式之前必須通過的「層」。每一層都可以檢查請求，甚至完全拒絕它。

所有中介層都透過服務容器解析，因此您可以在中介層的建構子中類型提示您需要的任何依賴項。

中介層與回應

當然，中介層可以在將請求更深入地傳遞到應用程式之前或之後執行任務。例如，以下中介層將在請求被應用程式處理之前執行某些任務

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

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class BeforeMiddleware
{
    public function handle(Request $request, Closure $next): Response
    {
        // Perform action

        return $next($request);
    }
}

但是，此中介層將在請求被應用程式處理之後執行其任務

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

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class AfterMiddleware
{
    public function handle(Request $request, Closure $next): Response
    {
        $response = $next($request);

        // Perform action

        return $response;
    }
}

註冊中介層

全域中介層

如果您希望中介層在每次對您應用程式的 HTTP 請求期間執行，您可以將其附加到您應用程式 bootstrap/app.php 檔案中的全域中介層堆疊。

1use App\Http\Middleware\EnsureTokenIsValid;
2 
3->withMiddleware(function (Middleware $middleware) {
4     $middleware->append(EnsureTokenIsValid::class);
5})

use App\Http\Middleware\EnsureTokenIsValid;

->withMiddleware(function (Middleware $middleware) {
     $middleware->append(EnsureTokenIsValid::class);
})

提供給 withMiddleware 閉包的 $middleware 物件是 Illuminate\Foundation\Configuration\Middleware 的一個實例，負責管理指派給您應用程式路由的中介層。append 方法將中介層添加到全域中介層列表的末尾。如果您想將中介層添加到列表的開頭，則應使用 prepend 方法。

手動管理 Laravel 的預設全域中介層

如果您想手動管理 Laravel 的全域中介層堆疊，您可以將 Laravel 的預設全域中介層堆疊提供給 use 方法。然後，您可以根據需要調整預設中介層堆疊。

 1->withMiddleware(function (Middleware $middleware) {
 2    $middleware->use([
 3        \Illuminate\Foundation\Http\Middleware\InvokeDeferredCallbacks::class,
 4        // \Illuminate\Http\Middleware\TrustHosts::class,
 5        \Illuminate\Http\Middleware\TrustProxies::class,
 6        \Illuminate\Http\Middleware\HandleCors::class,
 7        \Illuminate\Foundation\Http\Middleware\PreventRequestsDuringMaintenance::class,
 8        \Illuminate\Http\Middleware\ValidatePostSize::class,
 9        \Illuminate\Foundation\Http\Middleware\TrimStrings::class,
10        \Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull::class,
11    ]);
12})

->withMiddleware(function (Middleware $middleware) {
    $middleware->use([
        \Illuminate\Foundation\Http\Middleware\InvokeDeferredCallbacks::class,
        // \Illuminate\Http\Middleware\TrustHosts::class,
        \Illuminate\Http\Middleware\TrustProxies::class,
        \Illuminate\Http\Middleware\HandleCors::class,
        \Illuminate\Foundation\Http\Middleware\PreventRequestsDuringMaintenance::class,
        \Illuminate\Http\Middleware\ValidatePostSize::class,
        \Illuminate\Foundation\Http\Middleware\TrimStrings::class,
        \Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull::class,
    ]);
})

將中介層指派給路由

如果您想將中介層指派給特定路由，您可以在定義路由時調用 middleware 方法。

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

use App\Http\Middleware\EnsureTokenIsValid;

Route::get('/profile', function () {
    // ...
})->middleware(EnsureTokenIsValid::class);

您可以通過將中介層名稱陣列傳遞給 middleware 方法，將多個中介層指派給路由。

1Route::get('/', function () {
2    // ...
3})->middleware([First::class, Second::class]);

Route::get('/', function () {
    // ...
})->middleware([First::class, Second::class]);

排除中介層

當將中介層指派給一組路由時，您可能偶爾需要阻止中介層應用於群組內的個別路由。您可以使用 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});

use App\Http\Middleware\EnsureTokenIsValid;

Route::middleware([EnsureTokenIsValid::class])->group(function () {
    Route::get('/', function () {
        // ...
    });

    Route::get('/profile', function () {
        // ...
    })->withoutMiddleware([EnsureTokenIsValid::class]);
});

您也可以從整個路由定義群組中排除給定的一組中介層。

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

use App\Http\Middleware\EnsureTokenIsValid;

Route::withoutMiddleware([EnsureTokenIsValid::class])->group(function () {
    Route::get('/profile', function () {
        // ...
    });
});

withoutMiddleware 方法只能移除路由中介層，不適用於全域中介層。

中介層群組

有時您可能希望將多個中介層分組在單個鍵下，以便更輕鬆地將它們指派給路由。您可以使用應用程式 bootstrap/app.php 檔案中的 appendToGroup 方法完成此操作。

 1use App\Http\Middleware\First;
 2use App\Http\Middleware\Second;
 3 
 4->withMiddleware(function (Middleware $middleware) {
 5    $middleware->appendToGroup('group-name', [
 6        First::class,
 7        Second::class,
 8    ]);
 9 
10    $middleware->prependToGroup('group-name', [
11        First::class,
12        Second::class,
13    ]);
14})

use App\Http\Middleware\First;
use App\Http\Middleware\Second;

->withMiddleware(function (Middleware $middleware) {
    $middleware->appendToGroup('group-name', [
        First::class,
        Second::class,
    ]);

    $middleware->prependToGroup('group-name', [
        First::class,
        Second::class,
    ]);
})

可以使用與個別中介層相同的語法，將中介層群組指派給路由和控制器動作。

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

Route::get('/', function () {
    // ...
})->middleware('group-name');

Route::middleware(['group-name'])->group(function () {
    // ...
});

Laravel 的預設中介層群組

Laravel 包含預定義的 web 和 api 中介層群組，其中包含您可能想要應用於您的 web 和 API 路由的常見中介層。請記住，Laravel 會自動將這些中介層群組應用於相應的 routes/web.php 和 routes/api.php 檔案。

`web` 中介層群組
`Illuminate\Cookie\Middleware\EncryptCookies`
`Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse`
`Illuminate\Session\Middleware\StartSession`
`Illuminate\View\Middleware\ShareErrorsFromSession`
`Illuminate\Foundation\Http\Middleware\ValidateCsrfToken`
`Illuminate\Routing\Middleware\SubstituteBindings`

`api` 中介層群組
`Illuminate\Routing\Middleware\SubstituteBindings`

如果您想將中介層附加或前置到這些群組，您可以使用應用程式 bootstrap/app.php 檔案中的 web 和 api 方法。web 和 api 方法是 appendToGroup 方法的便捷替代方案。

 1use App\Http\Middleware\EnsureTokenIsValid;
 2use App\Http\Middleware\EnsureUserIsSubscribed;
 3 
 4->withMiddleware(function (Middleware $middleware) {
 5    $middleware->web(append: [
 6        EnsureUserIsSubscribed::class,
 7    ]);
 8 
 9    $middleware->api(prepend: [
10        EnsureTokenIsValid::class,
11    ]);
12})

use App\Http\Middleware\EnsureTokenIsValid;
use App\Http\Middleware\EnsureUserIsSubscribed;

->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        EnsureUserIsSubscribed::class,
    ]);

    $middleware->api(prepend: [
        EnsureTokenIsValid::class,
    ]);
})

您甚至可以用您自己的自訂中介層替換 Laravel 的預設中介層群組條目之一。

1use App\Http\Middleware\StartCustomSession;
2use Illuminate\Session\Middleware\StartSession;
3 
4$middleware->web(replace: [
5    StartSession::class => StartCustomSession::class,
6]);

use App\Http\Middleware\StartCustomSession;
use Illuminate\Session\Middleware\StartSession;

$middleware->web(replace: [
    StartSession::class => StartCustomSession::class,
]);

或者，您可以完全移除中介層。

1$middleware->web(remove: [
2    StartSession::class,
3]);

$middleware->web(remove: [
    StartSession::class,
]);

手動管理 Laravel 的預設中介層群組

如果您想手動管理 Laravel 的預設 web 和 api 中介層群組中的所有中介層，您可以完全重新定義這些群組。以下範例將使用其預設中介層定義 web 和 api 中介層群組，讓您可以根據需要自訂它們。

 1->withMiddleware(function (Middleware $middleware) {
 2    $middleware->group('web', [
 3        \Illuminate\Cookie\Middleware\EncryptCookies::class,
 4        \Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class,
 5        \Illuminate\Session\Middleware\StartSession::class,
 6        \Illuminate\View\Middleware\ShareErrorsFromSession::class,
 7        \Illuminate\Foundation\Http\Middleware\ValidateCsrfToken::class,
 8        \Illuminate\Routing\Middleware\SubstituteBindings::class,
 9        // \Illuminate\Session\Middleware\AuthenticateSession::class,
10    ]);
11 
12    $middleware->group('api', [
13        // \Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class,
14        // 'throttle:api',
15        \Illuminate\Routing\Middleware\SubstituteBindings::class,
16    ]);
17})

->withMiddleware(function (Middleware $middleware) {
    $middleware->group('web', [
        \Illuminate\Cookie\Middleware\EncryptCookies::class,
        \Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class,
        \Illuminate\Session\Middleware\StartSession::class,
        \Illuminate\View\Middleware\ShareErrorsFromSession::class,
        \Illuminate\Foundation\Http\Middleware\ValidateCsrfToken::class,
        \Illuminate\Routing\Middleware\SubstituteBindings::class,
        // \Illuminate\Session\Middleware\AuthenticateSession::class,
    ]);

    $middleware->group('api', [
        // \Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class,
        // 'throttle:api',
        \Illuminate\Routing\Middleware\SubstituteBindings::class,
    ]);
})

預設情況下，web 和 api 中介層群組會由 bootstrap/app.php 檔案自動應用於您應用程式的相應 routes/web.php 和 routes/api.php 檔案。

中介層別名

您可以在應用程式的 bootstrap/app.php 檔案中為中介層指派別名。中介層別名允許您為給定的中介層類別定義一個簡短的別名，這對於類別名稱較長的中介層尤其有用。

1use App\Http\Middleware\EnsureUserIsSubscribed;
2 
3->withMiddleware(function (Middleware $middleware) {
4    $middleware->alias([
5        'subscribed' => EnsureUserIsSubscribed::class
6    ]);
7})

use App\Http\Middleware\EnsureUserIsSubscribed;

->withMiddleware(function (Middleware $middleware) {
    $middleware->alias([
        'subscribed' => EnsureUserIsSubscribed::class
    ]);
})

一旦在中介層別名在您的應用程式 bootstrap/app.php 檔案中定義之後，您可以在將中介層指派給路由時使用該別名。

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

Route::get('/profile', function () {
    // ...
})->middleware('subscribed');

為了方便起見，Laravel 的某些內建中介層預設已設定別名。例如，auth 中介層是 Illuminate\Auth\Middleware\Authenticate 中介層的別名。以下是預設中介層別名的列表

別名	中介層
`auth`	`Illuminate\Auth\Middleware\Authenticate`
`auth.basic`	`Illuminate\Auth\Middleware\AuthenticateWithBasicAuth`
`auth.session`	`Illuminate\Session\Middleware\AuthenticateSession`
`cache.headers`	`Illuminate\Http\Middleware\SetCacheHeaders`
`can`	`Illuminate\Auth\Middleware\Authorize`
`guest`	`Illuminate\Auth\Middleware\RedirectIfAuthenticated`
`password.confirm`	`Illuminate\Auth\Middleware\RequirePassword`
`precognitive`	`Illuminate\Foundation\Http\Middleware\HandlePrecognitiveRequests`
`signed`	`Illuminate\Routing\Middleware\ValidateSignature`
`subscribed`	`\Spark\Http\Middleware\VerifyBillableIsSubscribed`
`throttle`	`Illuminate\Routing\Middleware\ThrottleRequests` 或 `Illuminate\Routing\Middleware\ThrottleRequestsWithRedis`
`verified`	`Illuminate\Auth\Middleware\EnsureEmailIsVerified`

排序中介層

在極少數情況下，您可能需要您的中介層以特定順序執行，但在將它們指派給路由時無法控制它們的順序。在這些情況下，您可以使用應用程式 bootstrap/app.php 檔案中的 priority 方法指定您的中介層優先順序。

 1->withMiddleware(function (Middleware $middleware) {
 2    $middleware->priority([
 3        \Illuminate\Foundation\Http\Middleware\HandlePrecognitiveRequests::class,
 4        \Illuminate\Cookie\Middleware\EncryptCookies::class,
 5        \Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class,
 6        \Illuminate\Session\Middleware\StartSession::class,
 7        \Illuminate\View\Middleware\ShareErrorsFromSession::class,
 8        \Illuminate\Foundation\Http\Middleware\ValidateCsrfToken::class,
 9        \Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class,
10        \Illuminate\Routing\Middleware\ThrottleRequests::class,
11        \Illuminate\Routing\Middleware\ThrottleRequestsWithRedis::class,
12        \Illuminate\Routing\Middleware\SubstituteBindings::class,
13        \Illuminate\Contracts\Auth\Middleware\AuthenticatesRequests::class,
14        \Illuminate\Auth\Middleware\Authorize::class,
15    ]);
16})

->withMiddleware(function (Middleware $middleware) {
    $middleware->priority([
        \Illuminate\Foundation\Http\Middleware\HandlePrecognitiveRequests::class,
        \Illuminate\Cookie\Middleware\EncryptCookies::class,
        \Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class,
        \Illuminate\Session\Middleware\StartSession::class,
        \Illuminate\View\Middleware\ShareErrorsFromSession::class,
        \Illuminate\Foundation\Http\Middleware\ValidateCsrfToken::class,
        \Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class,
        \Illuminate\Routing\Middleware\ThrottleRequests::class,
        \Illuminate\Routing\Middleware\ThrottleRequestsWithRedis::class,
        \Illuminate\Routing\Middleware\SubstituteBindings::class,
        \Illuminate\Contracts\Auth\Middleware\AuthenticatesRequests::class,
        \Illuminate\Auth\Middleware\Authorize::class,
    ]);
})

中介層參數

中介層還可以接收其他參數。例如，如果您的應用程式需要在執行給定動作之前驗證已驗證的使用者是否具有給定的「角色」，您可以建立一個 EnsureUserHasRole 中介層，該中介層接收角色名稱作為額外參數。

額外的中介層參數將在 $next 參數之後傳遞給中介層

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

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class EnsureUserHasRole
{
    /**
     * Handle an incoming request.
     *
     * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
     */
    public function handle(Request $request, Closure $next, string $role): Response
    {
        if (! $request->user()->hasRole($role)) {
            // Redirect...
        }

        return $next($request);
    }

}

在定義路由時，可以通過使用 : 分隔中介層名稱和參數來指定中介層參數

1use App\Http\Middleware\EnsureUserHasRole;
2 
3Route::put('/post/{id}', function (string $id) {
4    // ...
5})->middleware(EnsureUserHasRole::class.':editor');

use App\Http\Middleware\EnsureUserHasRole;

Route::put('/post/{id}', function (string $id) {
    // ...
})->middleware(EnsureUserHasRole::class.':editor');

多個參數可以用逗號分隔

1Route::put('/post/{id}', function (string $id) {
2    // ...
3})->middleware(EnsureUserHasRole::class.':editor,publisher');

Route::put('/post/{id}', function (string $id) {
    // ...
})->middleware(EnsureUserHasRole::class.':editor,publisher');

可終止的中介層

有時，中介層可能需要在 HTTP 回應已傳送到瀏覽器後執行一些工作。如果您在中介層上定義了 terminate 方法，並且您的 Web 伺服器正在使用 FastCGI，則在回應傳送到瀏覽器後，將自動呼叫 terminate 方法。

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

<?php

namespace Illuminate\Session\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class TerminatingMiddleware
{
    /**
     * Handle an incoming request.
     *
     * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
     */
    public function handle(Request $request, Closure $next): Response
    {
        return $next($request);
    }

    /**
     * Handle tasks after the response has been sent to the browser.
     */
    public function terminate(Request $request, Response $response): void
    {
        // ...
    }
}

terminate 方法應接收請求和回應。一旦您定義了可終止的中介層，您應該將其添加到您應用程式 bootstrap/app.php 檔案中的路由或全域中介層列表中。

當在中介層上呼叫 terminate 方法時，Laravel 將從服務容器解析中介層的新實例。如果您希望在呼叫 handle 和 terminate 方法時使用相同的中介層實例，請使用容器的 singleton 方法向容器註冊中介層。通常，這應該在您的 AppServiceProvider 的 register 方法中完成

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

use App\Http\Middleware\TerminatingMiddleware;

/**
 * Register any application services.
 */
public function register(): void
{
    $this->app->singleton(TerminatingMiddleware::class);
}

序言

開始使用

架構概念

基礎

深入探討

安全性

資料庫

Eloquent ORM

測試

套件

中介層

簡介

定義中介層

中介層與回應

註冊中介層

全域中介層

手動管理 Laravel 的預設全域中介層

將中介層指派給路由

排除中介層

中介層群組

Laravel 的預設中介層群組

手動管理 Laravel 的預設中介層群組

中介層別名

排序中介層

中介層參數

可終止的中介層

產品

套件

資源