Appearance
中间件
介绍
中间件提供了一种方便的机制来检查和筛选进入应用程序的 HTTP 请求。例如,Laravel 包含一个中间件,用于验证应用程序的用户是否经过身份验证。如果用户未经过身份验证,中间件会将用户重定向到应用程序的登录屏幕。但是,如果用户经过身份验证,中间件将允许请求进一步进入应用程序。
可以编写其他中间件来执行除身份验证之外的各种任务。例如,日志记录中间件可能会记录对应用程序的所有传入请求。Laravel 中包含了多种中间件,包括用于身份验证和 CSRF 保护的中间件;但是,所有用户定义的中间件通常都位于应用程序的 app/Http/Middleware
目录中。
定义中间件
要创建新的中间件,请使用 make:middleware
Artisan 命令:
shell
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 请求在达到应用程序之前必须通过的一系列“层”。每一层都可以检查请求,甚至完全拒绝请求
NOTE
所有中间件都通过服务容器解析,因此您可以在中间件的构造函数中对所需的任何依赖项进行类型提示。
中间件和响应
当然,中间件可以在将请求传递到应用程序更深一层之前或之后执行任务。例如,以下中间件会在请求被应用程序处理之前执行一些任务
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
{
// 执行操作
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);
// 执行操作
return $response;
}
}
注册中间件
全局中间件
如果你想在每次访问你的应用的 HTTP 请求中运行中间件,你可以在应用的 bootstrap/app.php
文件中将其附加到全局中间件堆栈中:
php
use App\Http\Middleware\EnsureTokenIsValid;
->withMiddleware(function (Middleware $middleware) {
$middleware->append(EnsureTokenIsValid::class);
})
提供的 $middleware
对象到 withMiddleware
闭包是一个 Illuminate\Foundation\Configuration\Middleware
的实例,负责管理分配给应用程序路由的中间件。 append
方法将中间件添加到全局中间件列表的末尾。如果您希望将中间件添加到列表的开头,应使用 prepend
方法。
手动管理 Laravel 的默认全局中间件
如果您希望手动管理 Laravel 的全局中间件堆栈,可以将 Laravel 的默认全局中间件堆栈提供给 use
方法。然后,可以根据需要调整默认的中间件堆栈:
php
->withMiddleware(function (Middleware $middleware) {
$middleware->use([
// \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 () {
// ...
});
});
withoutMiddleware
方法只能删除路由中间件,不适用于全局中间件。
中间件组
有时你可能希望将多个中间件分组到一个 key 下,以便更容易将它们分配给路由。您可以使用应用程序的 bootstrap/app.php
文件中的 appendToGroup
方法完成此操作:
php
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,
]);
})
中间件组可以使用与单个中间件相同的语法分配给路由和控制器操作:
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
文件:
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
方法的便捷替代方法:
php
use App\Http\Middleware\EnsureTokenIsValid;
use App\Http\Middleware\EnsureUserIsSubscribed;
->withMiddleware(function (Middleware $middleware) {
$middleware->web(append: [
EnsureUserIsSubscribed::class,
]);
$middleware->api(prepend: [
EnsureTokenIsValid::class,
]);
})
你甚至可以用你自己的自定义 middleware 替换 Laravel 的默认 middleware 组条目之一:
php
use App\Http\Middleware\StartCustomSession;
use Illuminate\Session\Middleware\StartSession;
$middleware->web(replace: [
StartSession::class => StartCustomSession::class,
]);
或者,你可以完全删除一个 middleware:
php
$middleware->web(remove: [
StartSession::class,
]);
手动管理 Laravel 的默认中间件组
如果你想手动管理 Laravel 的默认 Web
和 api
中间件组中的所有中间件,你可以完全重新定义这些组。下面的示例将使用默认中间件定义 Web
和 api
中间件组,允许您根据需要自定义它们:
php
->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,
]);
})
NOTE
默认情况下,bootstrap/app.php
文件会自动将 Web
和 API
中间件组应用于应用程序的相应 routes/web.php
和 routes/api.php
文件。
中间件别名
您可以在应用程序的 bootstrap/app.php
文件中为中间件分配别名。中间件别名允许你为给定的中间件类定义一个短别名,这对于具有长类名的中间件特别有用:
php
use App\Http\Middleware\EnsureUserIsSubscribed;
->withMiddleware(function (Middleware $middleware) {
$middleware->alias([
'subscribed' => EnsureUserIsSubscribed::class
]);
})
在应用程序的 bootstrap/app.php
文件中定义了中间件别名后,您可以在将中间件分配给路由时使用别名:
php
Route::get('/profile', function () {
// ...
})->middleware('subscribed');
为方便起见,Laravel 的一些内置中间件默认是别名的。例如,auth
中间件是中间件的 Illuminate\Auth\Middleware\Authenticate
别名。以下是默认中间件别名的列表:
Alias | Middleware |
---|---|
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 or Illuminate\Routing\Middleware\ThrottleRequestsWithRedis |
verified | Illuminate\Auth\Middleware\EnsureEmailIsVerified |
排序中间件
在极少数情况下,你可能需要 middleware 按特定顺序执行,但在将它们分配给路由时无法控制它们的顺序。在这些情况下,您可以使用应用程序的 bootstrap/app.php
文件中的 priority
方法指定中间件优先级:
php
->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
参数之后传递给中间件:
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
Route::put('/post/{id}', function (string $id) {
// ...
})->middleware('role:editor');
多个参数可以用逗号分隔:
php
Route::put('/post/{id}', function (string $id) {
// ...
})->middleware('role: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);
}