中间件

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

介绍

中间件提供了一种便捷的机制来检查和过滤进入应用程序的 HTTP 请求。例如，Laravel 包含一个中间件，用于验证应用程序用户是否已通过身份验证。如果用户未通过身份验证，中间件会将用户重定向到应用程序的登录屏幕。如果用户已通过身份验证，中间件将允许请求继续执行。

除了身份验证之外，还可以编写其他中间件来执行各种任务。例如，日志记录中间件可以记录所有传入应用程序的请求。Laravel 包含各种中间件，包括用于身份验证和 CSRF 保护的中间件；但是，所有用户定义的中间件通常位于应用程序的app/Http/Middleware目录中。

定义中间件

要创建新的中间件，请使用make:middlewareArtisan 命令：

1php artisan make:middleware EnsureTokenIsValid

php artisan make:middleware EnsureTokenIsValid

此命令将EnsureTokenIsValid在您的目录中放置一个新类app/Http/Middleware。在此中间件中，仅当提供的输入与指定值匹配时，我们才允许访问路由token。否则，我们将把用户重定向回/homeURI：

 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 重定向到客户端；否则，请求将被传递到应用程序的更深处。要将请求传递到应用程序的更深处（允许中间件“传递”），您应该$next使用调用回调函数$request。

最好将中间件设想为 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);
})

$middleware传递给闭包的对象是withMiddleware的一个实例Illuminate\Foundation\Configuration\Middleware，负责管理分配给应用程序路由的中间件。该append方法将中间件添加到全局中间件列表的末尾。如果您想将中间件添加到列表的开头，请使用该prepend方法。

手动管理 Laravel 的默认全局中间件

如果你想手动管理 Laravel 的全局中间件堆栈，可以向该use方法传入 Laravel 默认的全局中间件堆栈。然后，你可以根据需要调整默认中间件堆栈：

 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方法只能移除路由中间件，不适用于全局中间件。

中间件组

有时你可能希望将多个中间件归类到一个键下，以便更轻松地将它们分配给路由。你可以appendToGroup在应用程序bootstrap/app.php文件中使用以下方法来实现：

 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`

如果您想将中间件附加或添加到这些组中，您可以在应用程序文件中使用web和方法。和方法是的便捷替代方法：apibootstrap/app.phpwebapiappendToGroup

 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中间件组会由文件自动应用到您的应用程序对应的routes/web.php和routes/api.php文件中bootstrap/app.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`

排序中间件

极少数情况下，你可能需要中间件按特定顺序执行，但在分配给路由时无法控制它们的执行顺序。在这种情况下，你可以priority在应用程序bootstrap/app.php文件中使用以下命令指定中间件的优先级：

 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}

<?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文件中的路由或全局中间件列表中。

当调用中间件的方法时，Laravel 会从服务容器terminate中解析一个全新的中间件实例。如果您希望在调用和方法时使用同一个中间件实例，请使用容器的方法将中间件注册到容器中。通常，这应该在您的方法中完成：handleterminatesingletonregisterAppServiceProvider

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

测试

Packages

中间件

介绍

定义中间件

中间件和响应

注册中间件

全局中间件

手动管理 Laravel 的默认全局中间件

为路由分配中间件

排除中间件

中间件组

Laravel 的默认中间件组

手动管理 Laravel 的默认中间件组

中间件别名

排序中间件

中间件参数

可终止中间件

本页内容