中间件

简介
定义中间件
注册中间件
中间件参数
可终止的中间件

简介

中间件提供了一种方便的机制来检查和过滤进入应用程序的 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 的默认中间件组

中间件别名

中间件排序

中间件参数

可终止的中间件

产品

软件包

资源