请求
HTTP 请求
简介
Laravel 的 Illuminate\Http\Request 类提供了一种面向对象的方式,用于与你的应用程序当前正在处理的 HTTP 请求进行交互,并获取随请求提交的输入、Cookie 和文件。
与请求交互
访问请求
要通过依赖注入获取当前 HTTP 请求的实例,你应该在路由闭包或控制器方法中对 Illuminate\Http\Request 类进行类型提示。传入的请求实例将由 Laravel 服务容器 自动注入:
<?php
namespace App\Http\Controllers;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
class UserController extends Controller
{
/**
* 存储一个新用户。
*/
public function store(Request $request): RedirectResponse
{
$name = $request->input('name');
// 存储用户..
return redirect('/users');
}
}
如前所述,你也可以在路由闭包中对 Illuminate\Http\Request 类进行类型提示。服务容器会在闭包执行时自动将传入的请求注入其中:
use Illuminate\Http\Request;
Route::get('/', function (Request $request) {
// ...
});
依赖注入和路由参数
如果你的控制器方法还期望从路由参数接收输入,你应该将路由参数列在其他依赖之后。例如,如果你的路由是这样定义的:
use App\Http\Controllers\UserController;
Route::put('/user/{id}', [UserController::class, 'update']);
你仍然可以对 Illuminate\Http\Request 进行类型提示,并通过如下方式定义控制器方法来访问你的 id 路由参数:
<?php
namespace App\Http\Controllers;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
class UserController extends Controller
{
/**
* 更新指定用户。
*/
public function update(Request $request, string $id): RedirectResponse
{
// 更新用户...
return redirect('/users');
}
}
请求路径、主机和方法
Illuminate\Http\Request 实例提供了多种方法来检查传入的 HTTP 请求,并扩展了 Symfony\Component\HttpFoundation\Request 类。下面我们将讨论其中几个最重要的方法。
获取请求路径
path 方法返回请求的路径信息。因此,如果传入的请求目标是 http://example.com/foo/bar,path 方法将返回 foo/bar:
$uri = $request->path();
检查请求路径 / 路由
is 方法允许你验证传入的请求路径是否匹配给定模式。使用此方法时,你可以使用 * 字符作为通配符:
if ($request->is('admin/*')) {
// ...
}
使用 routeIs 方法,你可以判断传入的请求是否匹配了一个命名路由:
if ($request->routeIs('admin.*')) {
// ...
}
获取请求 URL
要获取传入请求的完整 URL,你可以使用 url 或 fullUrl 方法。url 方法将返回不包含查询字符串的 URL,而 fullUrl 方法则包含查询字符串:
$url = $request->url();
$urlWithQueryString = $request->fullUrl();
如果你想将查询字符串数据追加到当前 URL,可以调用 fullUrlWithQuery 方法。该方法会将给定的查询字符串变量数组与当前查询字符串合并:
$request->fullUrlWithQuery(['type' => 'phone']);
如果你想在获取当前 URL 时排除给定的查询字符串参数,可以使用 fullUrlWithoutQuery 方法:
$request->fullUrlWithoutQuery(['type']);
获取请求主机
你可以通过 host、httpHost 和 schemeAndHttpHost 方法获取传入请求的 “host”:
// http://localhost:8000
$request->host(); // localhost
$request->httpHost(); // localhost:8000
$request->schemeAndHttpHost(); // http://localhost:8000
获取请求方法
method 方法将返回请求的 HTTP 动词。你可以使用 isMethod 方法来验证 HTTP 动词是否匹配给定字符串:
$method = $request->method();
if ($request->isMethod('post')) {
// ...
}
请求头
你可以使用 header 方法从 Illuminate\Http\Request 实例中获取请求头。如果该请求头不存在于请求中,将返回 null。不过,header 方法接受一个可选的第二个参数,当请求中不存在该请求头时,将返回这个参数:
$value = $request->header('X-Header-Name');
$value = $request->header('X-Header-Name', 'default');
hasHeader 方法可用于判断请求是否包含给定的标头:
if ($request->hasHeader('X-Header-Name')) {
// ...
}
为方便起见,可以使用 bearerToken 方法从 Authorization 标头中获取 bearer token。如果不存在这样的标头,则会返回空字符串:
$token = $request->bearerToken();
请求 IP 地址
ip 方法可用于获取向你的应用程序发起请求的客户端的 IP 地址:
$ipAddress = $request->ip();
如果你想获取 IP 地址数组,包括所有由代理转发的客户端 IP 地址,可以使用 ips 方法。“原始”客户端 IP 地址将位于数组的末尾:
$ipAddresses = $request->ips();
一般来说,IP 地址应被视为不可信的、由用户控制的输入,并且仅用于信息展示目的。
内容协商
Laravel 提供了几个方法,用于通过 Accept 标头检查传入请求所请求的内容类型。首先,getAcceptableContentTypes 方法将返回一个包含请求所接受的所有内容类型的数组:
$contentTypes = $request->getAcceptableContentTypes();
accepts 方法接受一个内容类型数组,如果请求接受其中任意一种内容类型,则返回 true。否则,将返回 false:
if ($request->accepts(['text/html', 'application/json'])) {
// ...
}
你可以使用 prefers 方法来确定在给定的内容类型数组中,请求最偏好的内容类型是哪一个。如果请求不接受任何提供的内容类型,则会返回 null:
$preferred = $request->prefers(['text/html', 'application/json']);
由于许多应用程序只提供 HTML 或 JSON,因此你可以使用 expectsJson 方法快速判断传入请求是否期望 JSON 响应:
if ($request->expectsJson()) {
// ...
}
如果你需要判断请求是否特别偏好 Markdown,或者是否会在其他内容类型中接受 Markdown,例如在为 AI 代理或其他使用 Markdown 响应的客户端提供服务时,可以使用 wantsMarkdown 和 acceptsMarkdown 方法:
if ($request->wantsMarkdown()) {
// 客户端最偏好的内容类型是 text/markdown...
}
if ($request->acceptsMarkdown()) {
// 客户端接受 Markdown 响应...
}
PSR-7 请求
PSR-7 标准规定了 HTTP 消息的接口,包括请求和响应。如果你想获取 PSR-7 请求实例,而不是 Laravel 请求,则首先需要安装几个库。Laravel 使用 Symfony HTTP Message Bridge 组件将典型的 Laravel 请求和响应转换为 PSR-7 兼容的实现:
composer require symfony/psr-http-message-bridge
composer require nyholm/psr7
安装这些库后,你可以通过在路由闭包或控制器方法中对请求接口进行类型提示来获取 PSR-7 请求:
use Psr\Http\Message\ServerRequestInterface;
Route::get('/', function (ServerRequestInterface $request) {
// ...
});
[!注意]
如果你从路由或控制器返回 PSR-7 响应实例,它将自动转换回 Laravel 响应实例,并由框架显示。
输入
获取输入
获取所有输入数据
你可以使用 all 方法以 array 的形式获取传入请求的所有输入数据。无论传入请求来自 HTML 表单还是 XHR 请求,都可以使用此方法:
$input = $request->all();
使用 collect 方法,你可以将传入请求的所有输入数据作为 集合 获取:
$input = $request->collect();
collect 方法还允许你将传入请求输入的一个子集作为集合获取:
$request->collect('users')->each(function (string $user) {
// ...
});
获取输入值
使用几个简单的方法,你可以从 Illuminate\Http\Request 实例访问所有用户输入,而无需关心该请求使用了哪个 HTTP 动词。无论 HTTP 动词是什么,都可以使用 input 方法来获取用户输入:
$name = $request->input('name');
你可以将默认值作为第二个参数传递给 input 方法。如果请求中不存在所请求的输入值,则会返回此值:
$name = $request->input('name', 'Sally');
在处理包含数组输入的表单时,请使用“点”表示法访问数组:
$name = $request->input('products.0.name');
$names = $request->input('products.*.name');
你可以在不传递任何参数的情况下调用 input 方法,以便将所有输入值作为关联数组获取:
$input = $request->input();
从查询字符串获取输入
虽然 input 方法会从整个请求负载中获取值(包括查询字符串),但 query 方法只会从查询字符串中获取值:
$name = $request->query('name');
如果请求的查询字符串值数据不存在,则会返回该方法的第二个参数:
$name = $request->query('name', 'Helen');
你可以在不传递任何参数的情况下调用 query 方法,以便将所有查询字符串值作为关联数组获取:
$query = $request->query();
获取 JSON 输入值
向你的应用程序发送 JSON 请求时,只要请求的 Content-Type 标头已正确设置为 application/json,你就可以通过 input 方法访问 JSON 数据。你甚至可以使用“点”语法来获取嵌套在 JSON 数组 / 对象中的值:
$name = $request->input('user.name');
获取 Stringable 输入值
你可以使用 string 方法将请求数据作为 Illuminate\Support\Stringable 的实例获取,而不是将请求的输入数据作为原始 string 获取:
$name = $request->string('name')->trim();
获取整数输入值
要以整数形式获取输入值,可以使用 integer 方法。此方法会尝试将输入值转换为整数。如果输入不存在或转换失败,它将返回你指定的默认值。这对于分页或其他数值输入特别有用:
$perPage = $request->integer('per_page');
获取布尔输入值
在处理复选框等 HTML 元素时,你的应用程序可能会收到实际上是字符串的“真值”。例如,"true" 或 "on"。为方便起见,你可以使用 boolean 方法将这些值作为布尔值获取。boolean 方法会针对 1、"1"、true、"true"、"on" 和 "yes" 返回 true。所有其他值都将返回 false:
$archived = $request->boolean('archived');
获取数组输入值
可以使用 array 方法获取包含数组的输入值。此方法将始终把输入值转换为数组。如果请求不包含具有给定名称的输入值,则会返回一个空数组:
$versions = $request->array('versions');
获取日期输入值
为方便起见,可以使用 date 方法将包含日期 / 时间的输入值作为 Carbon 实例获取。如果请求不包含具有给定名称的输入值,则会返回 null:
$birthday = $request->date('birthday');
date 方法接受的第二个和第三个参数可分别用于指定日期的格式和时区:
$elapsed = $request->date('elapsed', '!H:i', 'Europe/Madrid');
如果输入值存在但格式无效,则会抛出 InvalidArgumentException;因此,建议你在调用 date 方法之前先验证输入。
获取时间间隔输入值
可以使用 interval 方法将包含持续时间的输入值作为 CarbonInterval 实例获取。如果请求不包含具有给定名称的输入值,则会返回 null:
$duration = $request->interval('duration');
如果输入值是数字,你可以将单位作为第二个参数提供。单位可以是字符串,例如 second、minute 或 day,也可以是 Carbon\Unit 枚举实例:
use Carbon\Unit;
$timeout = $request->interval('timeout', 'second');
$delay = $request->interval('delay', Unit::Minute);
如果输入值存在但格式无效,则会抛出 InvalidArgumentException;因此,建议你在调用 interval 方法之前验证输入。
检索枚举输入值
也可以从请求中检索与 PHP 枚举 对应的输入值。如果请求中不包含给定名称的输入值,或者枚举没有与输入值匹配的标量值,则会返回 null。enum 方法接受输入值的名称和枚举类作为其第一个和第二个参数:
use App\Enums\Status;
$status = $request->enum('status', Status::class);
你还可以提供一个默认值,当值缺失或无效时将返回该默认值:
$status = $request->enum('status', Status::class, Status::Pending);
如果输入值是与 PHP 枚举对应的值数组,你可以使用 enums 方法将该值数组检索为枚举实例:
use App\Enums\Product;
$products = $request->enums('products', Product::class);
通过动态属性检索输入
你也可以使用 Illuminate\Http\Request 实例上的动态属性访问用户输入。例如,如果你的应用程序表单之一包含 name 字段,你可以像这样访问该字段的值:
$name = $request->name;
使用动态属性时,Laravel 会首先在请求负载中查找该参数的值。如果不存在,Laravel 将在匹配路由的参数中搜索该字段。
检索部分输入数据
如果你需要检索输入数据的子集,可以使用 only 和 except 方法。这两个方法都接受单个 array 或动态参数列表:
$input = $request->only(['username', 'password']);
$input = $request->only('username', 'password');
$input = $request->except(['credit_card']);
$input = $request->except('credit_card');
[!警告]
only方法会返回你请求的所有键 / 值对;但是,它不会返回请求中不存在的键 / 值对。
输入存在性
你可以使用 has 方法来判断请求中是否存在某个值。如果该值存在于请求中,has 方法会返回 true:
if ($request->has('name')) {
// ...
}
当传入数组时,has 方法将判断所有指定的值是否都存在:
if ($request->has(['name', 'email'])) {
// ...
}
如果任意指定的值存在,hasAny 方法会返回 true:
if ($request->hasAny(['name', 'email'])) {
// ...
}
如果某个值存在于请求中,whenHas 方法将执行给定的闭包:
$request->whenHas('name', function (string $input) {
// ...
});
可以向 whenHas 方法传递第二个闭包,当指定的值不存在于请求中时将执行该闭包:
$request->whenHas('name', function (string $input) {
// The "name" value is present...
}, function () {
// The "name" value is not present...
});
如果你想判断请求中是否存在某个值且该值不是空字符串,可以使用 filled 方法:
if ($request->filled('name')) {
// ...
}
如果你想判断请求中是否缺少某个值,或者该值是空字符串,可以使用 isNotFilled 方法:
if ($request->isNotFilled('name')) {
// ...
}
当传入数组时,isNotFilled 方法将判断所有指定的值是否都缺失或为空:
if ($request->isNotFilled(['name', 'email'])) {
// ...
}
如果任意指定的值不是空字符串,anyFilled 方法会返回 true:
if ($request->anyFilled(['name', 'email'])) {
// ...
}
如果某个值存在于请求中且不是空字符串,whenFilled 方法将执行给定的闭包:
$request->whenFilled('name', function (string $input) {
// ...
});
可以向 whenFilled 方法传递第二个闭包,当指定的值不是“filled”时将执行该闭包:
$request->whenFilled('name', function (string $input) {
// "name" 值已填充...
}, function () {
// "name" 值未填充...
});
要判断请求中是否不存在给定的键,可以使用 missing 和 whenMissing 方法:
if ($request->missing('name')) {
// ...
}
$request->whenMissing('name', function () {
// "name" 值缺失...
}, function () {
// "name" 值存在...
});
合并额外输入
有时你可能需要手动将额外输入合并到请求现有的输入数据中。为此,可以使用 merge 方法。如果给定的输入键已经存在于请求中,它将被提供给 merge 方法的数据覆盖:
$request->merge(['votes' => 0]);
如果请求的输入数据中尚不存在对应的键,则可以使用 mergeIfMissing 方法将输入合并到请求中:
$request->mergeIfMissing(['votes' => 0]);
旧输入
Laravel 允许你在下一次请求期间保留上一次请求的输入。这个功能在检测到验证错误后重新填充表单时尤其有用。不过,如果你正在使用 Laravel 内置的 验证功能,你可能不需要直接手动使用这些会话输入闪存方法,因为 Laravel 的一些内置验证机制会自动调用它们。
将输入闪存到会话
Illuminate\Http\Request 类上的 flash 方法会将当前输入闪存到 会话 中,以便在用户下一次请求应用程序时可用:
$request->flash();
你还可以使用 flashOnly 和 flashExcept 方法将请求数据的子集闪存到会话中。这些方法有助于防止密码等敏感信息进入会话:
$request->flashOnly(['username', 'email']);
$request->flashExcept('password');
闪存输入后重定向
由于你通常会想要将输入闪存到会话中,然后重定向到上一页,因此可以使用 withInput 方法轻松地将输入闪存链式调用到重定向上:
return redirect('/form')->withInput();
return redirect()->route('user.create')->withInput();
return redirect('/form')->withInput(
$request->except('password')
);
检索旧输入
要从上一次请求中检索已闪存的输入,请在 Illuminate\Http\Request 实例上调用 old 方法。old 方法会从 会话 中拉取之前已闪存的输入数据:
$username = $request->old('username');
Laravel 还提供了一个全局 old 辅助函数。如果你要在 Blade 模板 中显示旧输入,使用 old 辅助函数重新填充表单会更加方便。如果给定字段不存在旧输入,则会返回 null:
<input type="text" name="username" value="{{ old('username') }}">
Cookie
从请求中检索 Cookie
Laravel 框架创建的所有 Cookie 都会被加密,并使用认证码进行签名,这意味着如果它们被客户端更改,就会被视为无效。要从请求中检索 Cookie 值,请在 Illuminate\Http\Request 实例上使用 cookie 方法:
$value = $request->cookie('name');
输入修剪与规范化
默认情况下,Laravel 会在应用程序的全局中间件栈中包含 Illuminate\Foundation\Http\Middleware\TrimStrings 和 Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull 中间件。这些中间件会自动修剪请求中所有传入的字符串字段,并将任何空字符串字段转换为 null。这使你无需在路由和控制器中担心这些规范化问题。
禁用输入规范化
如果你想对所有请求禁用此行为,可以在应用程序的 bootstrap/app.php 文件中调用 $middleware->remove 方法,从应用程序的中间件栈中移除这两个中间件:
use Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull;
use Illuminate\Foundation\Http\Middleware\TrimStrings;
->withMiddleware(function (Middleware $middleware): void {
$middleware->remove([
ConvertEmptyStringsToNull::class,
TrimStrings::class,
]);
})
如果你想针对应用程序中的部分请求禁用字符串裁剪和空字符串转换,可以在应用程序的 bootstrap/app.php 文件中使用 trimStrings 和 convertEmptyStringsToNull 中间件方法。这两个方法都接受一个闭包数组,这些闭包应返回 true 或 false,以指示是否应跳过输入规范化:
->withMiddleware(function (Middleware $middleware): void {
$middleware->convertEmptyStringsToNull(except: [
fn (Request $request) => $request->is('admin/*'),
]);
$middleware->trimStrings(except: [
fn (Request $request) => $request->is('admin/*'),
]);
})
文件
获取上传的文件
你可以使用 file 方法或动态属性,从 Illuminate\Http\Request 实例中获取上传的文件。file 方法会返回一个 Illuminate\Http\UploadedFile 类的实例,该类继承自 PHP 的 SplFileInfo 类,并提供了多种与文件交互的方法:
$file = $request->file('photo');
$file = $request->photo;
你可以使用 hasFile 方法判断请求中是否存在某个文件:
if ($request->hasFile('photo')) {
// ...
}
验证上传是否成功
除了检查文件是否存在之外,你还可以通过 isValid 方法验证文件上传过程中是否没有出现问题:
if ($request->file('photo')->isValid()) {
// ...
}
文件路径和扩展名
UploadedFile 类还包含用于访问文件完整限定路径及其扩展名的方法。extension 方法会尝试根据文件内容猜测文件的扩展名。这个扩展名可能与客户端提供的扩展名不同:
$path = $request->photo->path();
$extension = $request->photo->extension();
其他文件方法
UploadedFile 实例上还有多种其他可用方法。有关这些方法的更多信息,请查看该类的 API 文档。
存储上传的文件
要存储上传的文件,你通常会使用已配置的某个 文件系统。UploadedFile 类有一个 store 方法,会将上传的文件移动到你的某个磁盘中,该磁盘可以是本地文件系统中的某个位置,也可以是像 Amazon S3 这样的云存储位置。
store 方法接受文件应存储的路径,该路径是相对于文件系统已配置根目录的路径。此路径不应包含文件名,因为系统会自动生成一个唯一 ID 作为文件名。
store 方法还接受一个可选的第二个参数,用于指定应使用哪个磁盘来存储文件。该方法会返回文件相对于磁盘根目录的路径:
$path = $request->photo->store('images');
$path = $request->photo->store('images', 's3');
如果你不希望自动生成文件名,可以使用 storeAs 方法,该方法接受路径、文件名和磁盘名称作为参数:
$path = $request->photo->storeAs('images', 'filename.jpg');
$path = $request->photo->storeAs('images', 'filename.jpg', 's3');
[!注意]
有关 Laravel 中文件存储的更多信息,请查看完整的 文件存储文档。
配置受信任的代理
当你的应用程序运行在会终止 TLS / SSL 证书的负载均衡器后面时,你可能会注意到,在使用 url 辅助函数时,应用程序有时不会生成 HTTPS 链接。通常,这是因为你的应用程序接收到的是负载均衡器通过 80 端口转发过来的流量,因此并不知道自己应该生成安全链接。
为了解决这个问题,你可以启用 Laravel 应用程序中包含的 Illuminate\Http\Middleware\TrustProxies 中间件,它允许你快速自定义应用程序应信任的负载均衡器或代理。你应在应用程序的 bootstrap/app.php 文件中使用 trustProxies 中间件方法来指定受信任的代理:
->withMiddleware(function (Middleware $middleware): void {
$middleware->trustProxies(at: [
'192.168.1.1',
'10.0.0.0/8',
]);
})
除了配置受信任的代理之外,你还可以配置应被信任的代理请求头:
->withMiddleware(function (Middleware $middleware): void {
$middleware->trustProxies(headers: Request::HEADER_X_FORWARDED_FOR |
Request::HEADER_X_FORWARDED_HOST |
Request::HEADER_X_FORWARDED_PORT |
Request::HEADER_X_FORWARDED_PROTO |
Request::HEADER_X_FORWARDED_AWS_ELB
);
})
[!注意]
如果你正在使用 AWS Elastic Load Balancing,headers的值应为Request::HEADER_X_FORWARDED_AWS_ELB。如果你的负载均衡器使用的是来自 RFC 7239 的标准Forwarded请求头,则headers的值应为Request::HEADER_FORWARDED。有关可用于headers值的常量的更多信息,请查看 Symfony 关于 信任代理 的文档。
信任所有代理
如果你正在使用 Amazon AWS 或其他“云”负载均衡器提供商,你可能不知道实际负载均衡器的 IP 地址。在这种情况下,你可以使用 * 来信任所有代理:
->withMiddleware(function (Middleware $middleware): void {
$middleware->trustProxies(at: '*');
})
配置受信任的主机
默认情况下,无论 HTTP 请求的 Host 请求头内容是什么,Laravel 都会响应它收到的所有请求。此外,在 Web 请求期间为你的应用程序生成绝对 URL 时,也会使用 Host 请求头的值。
通常,你应该配置你的 Web 服务器,例如 Nginx 或 Apache,使其只将匹配指定主机名的请求发送到你的应用程序。但是,如果你无法直接自定义 Web 服务器,并且需要指示 Laravel 只响应某些主机名,则可以通过为你的应用程序启用 Illuminate\Http\Middleware\TrustHosts 中间件来实现。
要启用 TrustHosts 中间件,你应该在应用程序的 bootstrap/app.php 文件中调用 trustHosts 中间件方法。使用该方法的 at 参数,你可以指定应用程序应响应的主机名。主机名字符串会被视为正则表达式。带有其他 Host 请求头的传入请求将被拒绝:
->withMiddleware(function (Middleware $middleware): void {
$middleware->trustHosts(at: ['^laravel\.test$']);
})
默认情况下,来自应用程序 URL 子域名的请求也会被自动信任。如果你想禁用此行为,可以使用 subdomains 参数:
->withMiddleware(function (Middleware $middleware): void {
$middleware->trustHosts(at: ['^laravel\.test$'], subdomains: false);
})
如果你需要访问应用程序的配置文件或数据库来确定受信任的主机,可以向 at 参数提供一个闭包:
->withMiddleware(function (Middleware $middleware): void {
$middleware->trustHosts(at: fn () => config('app.trusted_hosts'));
})
本译文仅用于学习和交流目的,转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议,如果我们的工作有侵犯到您的权益,请及时联系我们。
Laravel 13 中文文档
关于 LearnKu
推荐文章: