中间件

引言
定义中间件
注册中间件
中间件参数
可终止中间件

引言

中间件提供了一种便捷的机制，用于检查和过滤进入你的应用程序的 HTTP 请求。例如，Laravel 包含一个中间件，它验证你的应用程序的用户是否已认证。如果用户未认证，中间件会将用户重定向到你的应用程序的登录界面。然而，如果用户已认证，中间件将允许请求进一步进入应用程序。

额外的中间件可以编写来执行除认证之外的各种任务。例如，一个日志中间件可能会记录所有进入你应用程序的请求。Laravel 中包含了各种中间件，包括用于认证和 CSRF 保护的中间件；然而，所有用户定义的中间件通常位于你应用程序的 app/Http/Middleware 目录中。

定义中间件

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

bash

php artisan make:middleware EnsureTokenIsValid

此命令将会在你的 app/Http/Middleware 目录中放置一个新的 EnsureTokenIsValid 类。在此中间件中，如果所提供的 token 输入与指定值匹配，我们将只允许访问该路由。否则，我们将会把用户重定向回 /home URI：

php

<?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请求在到达您的应用程序之前必须穿过这些“层”。每一层都可以检查请求，甚至完全拒绝它。

[!注意]
所有中间件都通过服务容器解析，因此你可以在中间件的构造函数中类型提示任何所需的依赖项。

中间件和响应

当然，中间件可以在将请求进一步传递到应用程序之前或之后执行任务。例如，以下中间件将在请求被应用程序处理之前执行一些任务：

php

<?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);
    }
}

然而，这个中间件会在请求被应用程序处理之后执行其任务：

php

<?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 文件中的全局中间件堆栈：

php

use App\Http\Middleware\EnsureTokenIsValid;

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

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

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

如果您希望手动管理 Laravel 的全局中间件栈，您可以将 Laravel 的默认全局中间件栈提供给 use 方法。然后，您可以根据需要调整默认中间件栈：

php

->withMiddleware(function (Middleware $middleware): void {
    $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 方法：

php

use App\Http\Middleware\EnsureTokenIsValid;

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

您可以通过向 middleware 方法传递一个中间件名称数组，来为路由分配多个中间件：

php

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

不包括中间件

当给一组路由分配中间件时，您可能偶尔需要阻止该中间件应用于该组中的单个路由。您可以使用 withoutMiddleware 方法来实现此目的：

php

use App\Http\Middleware\EnsureTokenIsValid;

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

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

您还可以从整个组路由定义中排除一组给定的中间件：

php

use App\Http\Middleware\EnsureTokenIsValid;

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

The withoutMiddleware method can only remove route middleware and does not apply to global middleware.

中间件组

有时，您可能希望将多个中间件归于一个键下，以便更容易地将它们分配给路由。您可以使用应用程序的 bootstrap/app.php 文件中的 appendToGroup 方法来完成此操作：

php

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

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

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

中间件组可以使用与单个中间件相同的语法分配给路由和控制器动作：

php

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 文件：

如果您想向这些组追加或前置中间件，您可以使用应用程序 bootstrap/app.php 文件中的 web 和 api 方法。web 和 api 方法是 appendToGroup 方法的便捷替代方案：

php

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

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

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

您甚至可以用您自己的自定义中间件替换 Laravel 的默认中间件组条目：

php

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

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

或者，您可以彻底移除一个中间件：

php

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

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

如果您想手动管理 Laravel 默认 web 和 api 中间件组中的所有中间件，您可以完全重新定义这些组。以下示例将定义 web 和 api 中间件组及其默认中间件，以便您根据需要进行自定义：

php

->withMiddleware(function (Middleware $middleware): void {
    $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 文件中为中间件分配别名。中间件别名允许你为给定的中间件类定义一个简短的别名，这对于类名较长的中间件尤其有用：

php

use App\Http\Middleware\EnsureUserIsSubscribed;

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

一旦在你的应用程序的 bootstrap/app.php 文件中定义了中间件别名，你就可以在将中间件分配给路由时使用该别名：

php

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

为了方便，Laravel 某些内置中间件在默认情况下已别名化。例如，auth 中间件是 Illuminate\Auth\Middleware\Authenticate 中间件的别名。下面是默认中间件别名的列表：

排序中间件

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

php

->withMiddleware(function (Middleware $middleware): void {
    $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 参数之后传递给中间件：

php

<?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);
    }
}

中间件参数可以在定义路由时指定，通过使用 : 分隔中间件名称和参数：

php

use App\Http\Middleware\EnsureUserHasRole;

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

多个参数可由逗号分隔：

php

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

可终止中间件

有时中间件可能需要在 HTTP 响应发送到浏览器后做一些工作。如果你在中间件上定义了一个 terminate 方法，并且你的 Web 服务器正在使用 FastCGI，那么 terminate 方法将在响应发送到浏览器后自动被调用：

php

<?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 方法中完成：

php

use App\Http\Middleware\TerminatingMiddleware;

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

中间件

引言
定义中间件
注册中间件
中间件参数
可终止中间件

引言

定义中间件

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

bash

php artisan make:middleware EnsureTokenIsValid

php

<?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);
    }
}

最好将中间件设想为一系列“层”，HTTP请求在到达您的应用程序之前必须穿过这些“层”。每一层都可以检查请求，甚至完全拒绝它。

[!注意]
所有中间件都通过服务容器解析，因此你可以在中间件的构造函数中类型提示任何所需的依赖项。

中间件和响应

当然，中间件可以在将请求进一步传递到应用程序之前或之后执行任务。例如，以下中间件将在请求被应用程序处理之前执行一些任务：

php

<?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);
    }
}

然而，这个中间件会在请求被应用程序处理之后执行其任务：

php

<?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 文件中的全局中间件堆栈：

php

use App\Http\Middleware\EnsureTokenIsValid;

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

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

如果您希望手动管理 Laravel 的全局中间件栈，您可以将 Laravel 的默认全局中间件栈提供给 use 方法。然后，您可以根据需要调整默认中间件栈：

php

->withMiddleware(function (Middleware $middleware): void {
    $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 方法：

php

use App\Http\Middleware\EnsureTokenIsValid;

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

您可以通过向 middleware 方法传递一个中间件名称数组，来为路由分配多个中间件：

php

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

不包括中间件

当给一组路由分配中间件时，您可能偶尔需要阻止该中间件应用于该组中的单个路由。您可以使用 withoutMiddleware 方法来实现此目的：

php

use App\Http\Middleware\EnsureTokenIsValid;

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

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

您还可以从整个组路由定义中排除一组给定的中间件：

php

use App\Http\Middleware\EnsureTokenIsValid;

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

The withoutMiddleware method can only remove route middleware and does not apply to global middleware.

中间件组

php

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

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

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

中间件组可以使用与单个中间件相同的语法分配给路由和控制器动作：

php

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

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

Laravel 的默认中间件组

php

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

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

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

您甚至可以用您自己的自定义中间件替换 Laravel 的默认中间件组条目：

php

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

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

或者，您可以彻底移除一个中间件：

php

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

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

php

->withMiddleware(function (Middleware $middleware): void {
    $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 文件。

中间件别名

php

use App\Http\Middleware\EnsureUserIsSubscribed;

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

一旦在你的应用程序的 bootstrap/app.php 文件中定义了中间件别名，你就可以在将中间件分配给路由时使用该别名：

php

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

排序中间件

php

->withMiddleware(function (Middleware $middleware): void {
    $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,
    ]);
})

中间件参数

额外的中间件参数将在 $next 参数之后传递给中间件：

php

<?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);
    }
}

中间件参数可以在定义路由时指定，通过使用 : 分隔中间件名称和参数：

php

use App\Http\Middleware\EnsureUserHasRole;

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

多个参数可由逗号分隔：

php

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

可终止中间件

php

<?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
    {
        // ...
    }
}

php

use App\Http\Middleware\TerminatingMiddleware;

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

文档导航

中间件

引言

定义中间件

中间件和响应

注册中间件

全局中间件

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

将中间件分配给路由

不包括中间件

中间件组

Laravel 的默认中间件组

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

中间件别名

排序中间件

中间件参数

可终止中间件

中间件

引言

定义中间件

中间件和响应

注册中间件

全局中间件

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

将中间件分配给路由

不包括中间件

中间件组

Laravel 的默认中间件组

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

中间件别名

排序中间件

中间件参数

可终止中间件