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