跳到内容

HTTP 请求

简介

Laravel 的 Illuminate\Http\Request 类提供了一种面向对象的方式来与应用程序正在处理的当前 HTTP 请求进行交互,并检索随请求提交的输入、Cookie 和文件。

与请求交互

访问请求

要通过依赖注入获取当前 HTTP 请求的实例,您应该在路由闭包或控制器方法中类型提示 Illuminate\Http\Request 类。传入的请求实例将由 Laravel 服务容器 自动注入

1<?php
2 
3namespace App\Http\Controllers;
4 
5use Illuminate\Http\RedirectResponse;
6use Illuminate\Http\Request;
7 
8class UserController extends Controller
9{
10 /**
11 * Store a new user.
12 */
13 public function store(Request $request): RedirectResponse
14 {
15 $name = $request->input('name');
16 
17 // Store the user...
18 
19 return redirect('/users');
20 }
21}

如前所述,您也可以在路由闭包中类型提示 Illuminate\Http\Request 类。当执行闭包时,服务容器将自动将传入的请求注入到闭包中

1use Illuminate\Http\Request;
2 
3Route::get('/', function (Request $request) {
4 // ...
5});

依赖注入和路由参数

如果您的控制器方法也期望从路由参数获取输入,您应该在其他依赖项之后列出您的路由参数。例如,如果您的路由定义如下

1use App\Http\Controllers\UserController;
2 
3Route::put('/user/{id}', [UserController::class, 'update']);

您仍然可以类型提示 Illuminate\Http\Request 并通过将控制器方法定义如下来访问您的 id 路由参数

1<?php
2 
3namespace App\Http\Controllers;
4 
5use Illuminate\Http\RedirectResponse;
6use Illuminate\Http\Request;
7 
8class UserController extends Controller
9{
10 /**
11 * Update the specified user.
12 */
13 public function update(Request $request, string $id): RedirectResponse
14 {
15 // Update the user...
16 
17 return redirect('/users');
18 }
19}

请求路径、主机和方法

Illuminate\Http\Request 实例提供了多种方法来检查传入的 HTTP 请求,并扩展了 Symfony\Component\HttpFoundation\Request 类。我们将在下面讨论一些最重要的​​方法。

检索请求路径

path 方法返回请求的路径信息。因此,如果传入的请求的目标是 http://example.com/foo/bar,则 path 方法将返回 foo/bar

1$uri = $request->path();

检查请求路径/路由

is 方法允许您验证传入的请求路径是否与给定的模式匹配。使用此方法时,您可以将 * 字符用作通配符

1if ($request->is('admin/*')) {
2 // ...
3}

使用 routeIs 方法,您可以确定传入的请求是否与命名路由匹配

1if ($request->routeIs('admin.*')) {
2 // ...
3}

检索请求 URL

要检索传入请求的完整 URL,您可以使用 urlfullUrl 方法。url 方法将返回不带查询字符串的 URL,而 fullUrl 方法包括查询字符串

1$url = $request->url();
2 
3$urlWithQueryString = $request->fullUrl();

如果您想将查询字符串数据附加到当前 URL,您可以调用 fullUrlWithQuery 方法。此方法将给定的查询字符串变量数组与当前查询字符串合并

1$request->fullUrlWithQuery(['type' => 'phone']);

如果您想获取不带给定查询字符串参数的当前 URL,您可以使用 fullUrlWithoutQuery 方法

1$request->fullUrlWithoutQuery(['type']);

检索请求主机

您可以通过 hosthttpHostschemeAndHttpHost 方法检索传入请求的“主机”

1$request->host();
2$request->httpHost();
3$request->schemeAndHttpHost();

检索请求方法

method 方法将返回请求的 HTTP 动词。您可以使用 isMethod 方法验证 HTTP 动词是否与给定的字符串匹配

1$method = $request->method();
2 
3if ($request->isMethod('post')) {
4 // ...
5}

请求标头

您可以使用 header 方法从 Illuminate\Http\Request 实例检索请求标头。如果请求中不存在标头,则将返回 null。但是,header 方法接受一个可选的第二个参数,如果请求中不存在标头,则将返回该参数

1$value = $request->header('X-Header-Name');
2 
3$value = $request->header('X-Header-Name', 'default');

hasHeader 方法可用于确定请求是否包含给定的标头

1if ($request->hasHeader('X-Header-Name')) {
2 // ...
3}

为了方便起见,bearerToken 方法可用于从 Authorization 标头检索不记名令牌。如果不存在此类标头,则将返回空字符串

1$token = $request->bearerToken();

请求 IP 地址

ip 方法可用于检索向您的应用程序发出请求的客户端的 IP 地址

1$ipAddress = $request->ip();

如果您想检索 IP 地址数组,包括代理转发的所有客户端 IP 地址,您可以使用 ips 方法。“原始”客户端 IP 地址将位于数组的末尾

1$ipAddresses = $request->ips();

通常,IP 地址应被视为不受信任的、用户控制的输入,并且仅用于提供信息。

内容协商

Laravel 提供了几种方法来通过 Accept 标头检查传入请求的请求内容类型。首先,getAcceptableContentTypes 方法将返回一个数组,其中包含请求接受的所有内容类型

1$contentTypes = $request->getAcceptableContentTypes();

accepts 方法接受内容类型数组,如果请求接受任何内容类型,则返回 true。否则,将返回 false

1if ($request->accepts(['text/html', 'application/json'])) {
2 // ...
3}

您可以使用 prefers 方法来确定请求最偏好的给定内容类型数组中的哪种内容类型。如果请求不接受提供的任何内容类型,则将返回 null

1$preferred = $request->prefers(['text/html', 'application/json']);

由于许多应用程序仅服务于 HTML 或 JSON,因此您可以使用 expectsJson 方法快速确定传入的请求是否期望 JSON 响应

1if ($request->expectsJson()) {
2 // ...
3}

PSR-7 请求

PSR-7 标准 指定了 HTTP 消息的接口,包括请求和响应。如果您想获取 PSR-7 请求的实例而不是 Laravel 请求,您首先需要安装一些库。Laravel 使用Symfony HTTP Message Bridge组件将典型的 Laravel 请求和响应转换为 PSR-7 兼容的实现

1composer require symfony/psr-http-message-bridge
2composer require nyholm/psr7

安装这些库后,您可以通过在路由闭包或控制器方法中类型提示请求接口来获取 PSR-7 请求

1use Psr\Http\Message\ServerRequestInterface;
2 
3Route::get('/', function (ServerRequestInterface $request) {
4 // ...
5});

如果您从路由或控制器返回 PSR-7 响应实例,它将自动转换回 Laravel 响应实例并由框架显示。

输入

检索输入

检索所有输入数据

您可以使用 all 方法将所有传入请求的输入数据作为 array 检索。无论传入的请求来自 HTML 表单还是 XHR 请求,都可以使用此方法

1$input = $request->all();

使用 collect 方法,您可以将所有传入请求的输入数据作为集合检索

1$input = $request->collect();

collect 方法还允许您检索传入请求的输入子集作为集合

1$request->collect('users')->each(function (string $user) {
2 // ...
3});

检索输入值

使用一些简单的方法,您可以从 Illuminate\Http\Request 实例访问所有用户输入,而无需担心请求使用了哪个 HTTP 动词。无论 HTTP 动词是什么,都可以使用 input 方法来检索用户输入

1$name = $request->input('name');

您可以将默认值作为第二个参数传递给 input 方法。如果请求中不存在请求的输入值,则将返回此值

1$name = $request->input('name', 'Sally');

当使用包含数组输入的表单时,请使用“点”表示法来访问数组

1$name = $request->input('products.0.name');
2 
3$names = $request->input('products.*.name');

您可以调用不带任何参数的 input 方法,以便将所有输入值作为关联数组检索

1$input = $request->input();

从查询字符串检索输入

虽然 input 方法从整个请求负载(包括查询字符串)检索值,但 query 方法仅从查询字符串检索值

1$name = $request->query('name');

如果请求的查询字符串值数据不存在,则将返回此方法的第二个参数

1$name = $request->query('name', 'Helen');

您可以调用不带任何参数的 query 方法,以便将所有查询字符串值作为关联数组检索

1$query = $request->query();

检索 JSON 输入值

当向您的应用程序发送 JSON 请求时,只要请求的 Content-Type 标头正确设置为 application/json,您就可以通过 input 方法访问 JSON 数据。您甚至可以使用“点”语法来检索嵌套在 JSON 数组/对象中的值

1$name = $request->input('user.name');

检索 Stringable 输入值

您可以不将请求的输入数据作为原始 string 检索,而是使用 string 方法将请求数据作为 Illuminate\Support\Stringable 的实例检索

1$name = $request->string('name')->trim();

检索整数输入值

要将输入值作为整数检索,您可以使用 integer 方法。此方法将尝试将输入值强制转换为整数。如果输入不存在或强制转换失败,它将返回您指定的默认值。这对于分页或其他数字输入特别有用

1$perPage = $request->integer('per_page');

检索布尔值输入值

当处理复选框等 HTML 元素时,您的应用程序可能会收到实际上是字符串的“真值”。例如,“true”或“on”。为方便起见,您可以使用 boolean 方法将这些值作为布尔值检索。对于 1、“1”、true、“true”、“on”和“yes”,boolean 方法返回 true。所有其他值将返回 false

1$archived = $request->boolean('archived');

检索日期输入值

为方便起见,可以使用 date 方法将包含日期/时间的输入值作为 Carbon 实例检索。如果请求不包含具有给定名称的输入值,则将返回 null

1$birthday = $request->date('birthday');

date 方法接受的第二个和第三个参数可用于分别指定日期的格式和时区

1$elapsed = $request->date('elapsed', '!H:i', 'Europe/Madrid');

如果输入值存在但格式无效,将抛出 InvalidArgumentException 异常;因此,建议您在调用 date 方法之前验证输入。

检索枚举输入值

PHP 枚举 相对应的输入值也可以从请求中检索。如果请求不包含具有给定名称的输入值,或者枚举没有与输入值匹配的支持值,则将返回 nullenum 方法接受输入值的名称和枚举类作为其第一个和第二个参数

1use App\Enums\Status;
2 
3$status = $request->enum('status', Status::class);

如果输入值是与 PHP 枚举对应的值数组,则可以使用 enums 方法检索值数组作为枚举实例

1use App\Enums\Product;
2 
3$products = $request->enums('products', Product::class);

通过动态属性检索输入

您还可以使用 Illuminate\Http\Request 实例上的动态属性来访问用户输入。例如,如果您的应用程序的某个表单包含 name 字段,您可以像这样访问该字段的值

1$name = $request->name;

当使用动态属性时,Laravel 将首先在请求负载中查找参数的值。如果不存在,Laravel 将在匹配路由的参数中搜索该字段。

检索部分输入数据

如果您需要检索输入数据的子集,可以使用 onlyexcept 方法。这两种方法都接受单个 array 或动态参数列表

1$input = $request->only(['username', 'password']);
2 
3$input = $request->only('username', 'password');
4 
5$input = $request->except(['credit_card']);
6 
7$input = $request->except('credit_card');

only 方法返回您请求的所有键/值对;但是,它不会返回请求中不存在的键/值对。

输入存在

您可以使用 has 方法来确定请求中是否存在某个值。如果请求中存在该值,has 方法将返回 true

1if ($request->has('name')) {
2 // ...
3}

当给定一个数组时,has 方法将确定所有指定的值是否都存在

1if ($request->has(['name', 'email'])) {
2 // ...
3}

如果任何指定的值存在,hasAny 方法将返回 true

1if ($request->hasAny(['name', 'email'])) {
2 // ...
3}

如果请求中存在某个值,whenHas 方法将执行给定的闭包

1$request->whenHas('name', function (string $input) {
2 // ...
3});

可以将第二个闭包传递给 whenHas 方法,如果请求中不存在指定的值,则将执行该闭包

1$request->whenHas('name', function (string $input) {
2 // The "name" value is present...
3}, function () {
4 // The "name" value is not present...
5});

如果您想确定请求中是否存在某个值且不是空字符串,可以使用 filled 方法

1if ($request->filled('name')) {
2 // ...
3}

如果您想确定请求中缺少某个值或该值是空字符串,可以使用 isNotFilled 方法

1if ($request->isNotFilled('name')) {
2 // ...
3}

当给定一个数组时,isNotFilled 方法将确定所有指定的值是否都缺失或为空

1if ($request->isNotFilled(['name', 'email'])) {
2 // ...
3}

如果任何指定的值不是空字符串,anyFilled 方法将返回 true

1if ($request->anyFilled(['name', 'email'])) {
2 // ...
3}

如果请求中存在某个值且不是空字符串,whenFilled 方法将执行给定的闭包

1$request->whenFilled('name', function (string $input) {
2 // ...
3});

可以将第二个闭包传递给 whenFilled 方法,如果指定的值未“填充”,则将执行该闭包

1$request->whenFilled('name', function (string $input) {
2 // The "name" value is filled...
3}, function () {
4 // The "name" value is not filled...
5});

要确定请求中是否缺少给定的键,可以使用 missingwhenMissing 方法

1if ($request->missing('name')) {
2 // ...
3}
4 
5$request->whenMissing('name', function () {
6 // The "name" value is missing...
7}, function () {
8 // The "name" value is present...
9});

合并其他输入

有时您可能需要手动将额外的输入合并到请求的现有输入数据中。要完成此操作,您可以使用 merge 方法。如果给定的输入键已存在于请求中,它将被提供给 merge 方法的数据覆盖

1$request->merge(['votes' => 0]);

如果请求的输入数据中尚不存在相应的键,则可以使用 mergeIfMissing 方法将输入合并到请求中

1$request->mergeIfMissing(['votes' => 0]);

旧输入

Laravel 允许您在下一次请求期间保留来自一次请求的输入。此功能对于在检测到验证错误后重新填充表单特别有用。但是,如果您正在使用 Laravel 内置的 验证功能,则您可能不需要直接手动使用这些会话输入闪存方法,因为 Laravel 的某些内置验证工具会自动调用它们。

将输入闪存到会话

Illuminate\Http\Request 类上的 flash 方法会将当前输入闪存到 会话 中,以便在用户下次对应用程序的请求期间可用

1$request->flash();

您还可以使用 flashOnlyflashExcept 方法将请求数据的子集闪存到会话。这些方法对于将密码等敏感信息保留在会话之外很有用

1$request->flashOnly(['username', 'email']);
2 
3$request->flashExcept('password');

闪存输入然后重定向

由于您通常希望将输入闪存到会话,然后重定向到上一页,因此您可以轻松地使用 withInput 方法将输入闪存链接到重定向

1return redirect('/form')->withInput();
2 
3return redirect()->route('user.create')->withInput();
4 
5return redirect('/form')->withInput(
6 $request->except('password')
7);

检索旧输入

要从上一次请求中检索闪存的输入,请在 Illuminate\Http\Request 实例上调用 old 方法。old 方法将从 会话 中拉取先前闪存的输入数据

1$username = $request->old('username');

Laravel 还提供了一个全局 old 辅助函数。如果您在 Blade 模板 中显示旧输入,则使用 old 辅助函数重新填充表单会更方便。如果给定字段不存在旧输入,则将返回 null

1<input type="text" name="username" value="{{ old('username') }}">

Cookies

从请求中检索 Cookie

Laravel 框架创建的所有 Cookie 都经过加密并使用身份验证代码签名,这意味着如果客户端更改了它们,它们将被视为无效。要从请求中检索 Cookie 值,请在 Illuminate\Http\Request 实例上使用 cookie 方法

1$value = $request->cookie('name');

输入修剪和规范化

默认情况下,Laravel 在应用程序的全局中间件堆栈中包含 Illuminate\Foundation\Http\Middleware\TrimStringsIlluminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull 中间件。这些中间件将自动修剪请求上的所有传入字符串字段,并将任何空字符串字段转换为 null。这使您不必担心路由和控制器中的这些规范化问题。

禁用输入规范化

如果您想为所有请求禁用此行为,您可以通过在应用程序的 bootstrap/app.php 文件中调用 $middleware->remove 方法,从应用程序的中间件堆栈中删除这两个中间件

1use Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull;
2use Illuminate\Foundation\Http\Middleware\TrimStrings;
3 
4->withMiddleware(function (Middleware $middleware) {
5 $middleware->remove([
6 ConvertEmptyStringsToNull::class,
7 TrimStrings::class,
8 ]);
9})

如果您想为应用程序的请求子集禁用字符串修剪和空字符串转换,您可以在应用程序的 bootstrap/app.php 文件中使用 trimStringsconvertEmptyStringsToNull 中间件方法。这两种方法都接受一个闭包数组,这些闭包应返回 truefalse 以指示是否应跳过输入规范化

1->withMiddleware(function (Middleware $middleware) {
2 $middleware->convertEmptyStringsToNull(except: [
3 fn (Request $request) => $request->is('admin/*'),
4 ]);
5 
6 $middleware->trimStrings(except: [
7 fn (Request $request) => $request->is('admin/*'),
8 ]);
9})

文件

检索上传的文件

您可以使用 file 方法或使用动态属性从 Illuminate\Http\Request 实例中检索上传的文件。file 方法返回 Illuminate\Http\UploadedFile 类的实例,该类扩展了 PHP SplFileInfo 类,并提供了多种与文件交互的方法

1$file = $request->file('photo');
2 
3$file = $request->photo;

您可以使用 hasFile 方法确定请求中是否存在文件

1if ($request->hasFile('photo')) {
2 // ...
3}

验证成功上传

除了检查文件是否存在之外,您还可以通过 isValid 方法验证上传文件时是否没有问题

1if ($request->file('photo')->isValid()) {
2 // ...
3}

文件路径和扩展名

UploadedFile 类还包含用于访问文件的完全限定路径及其扩展名的方法。extension 方法将尝试根据文件的内容猜测文件的扩展名。此扩展名可能与客户端提供的扩展名不同

1$path = $request->photo->path();
2 
3$extension = $request->photo->extension();

其他文件方法

UploadedFile 实例上还有许多其他方法可用。有关这些方法的更多信息,请查看 该类的 API 文档

存储上传的文件

要存储上传的文件,您通常会使用配置的 文件系统 之一。UploadedFile 类有一个 store 方法,该方法会将上传的文件移动到您的磁盘之一,这可以是本地文件系统上的位置,也可以是像 Amazon S3 这样的云存储位置。

store 方法接受文件应存储的路径,该路径相对于文件系统的配置根目录。此路径不应包含文件名,因为将自动生成唯一 ID 作为文件名。

store 方法还接受一个可选的第二个参数,用于应使用哪个磁盘来存储文件。该方法将返回文件相对于磁盘根目录的路径

1$path = $request->photo->store('images');
2 
3$path = $request->photo->store('images', 's3');

如果您不希望自动生成文件名,可以使用 storeAs 方法,该方法接受路径、文件名和磁盘名称作为其参数

1$path = $request->photo->storeAs('images', 'filename.jpg');
2 
3$path = $request->photo->storeAs('images', 'filename.jpg', 's3');

有关 Laravel 中文件存储的更多信息,请查看完整的 文件存储文档

配置受信任的代理

当在终止 TLS/SSL 证书的负载均衡器后面运行应用程序时,您可能会注意到在使用 url 辅助函数时,您的应用程序有时不会生成 HTTPS 链接。通常,这是因为您的应用程序正在从端口 80 上的负载均衡器转发流量,并且不知道它应该生成安全链接。

要解决此问题,您可以启用 Laravel 应用程序中包含的 Illuminate\Http\Middleware\TrustProxies 中间件,这使您可以快速自定义应用程序应信任的负载均衡器或代理。您受信任的代理应使用应用程序 bootstrap/app.php 文件中的 trustProxies 中间件方法指定

1->withMiddleware(function (Middleware $middleware) {
2 $middleware->trustProxies(at: [
3 '192.168.1.1',
4 '10.0.0.0/8',
5 ]);
6})

除了配置受信任的代理之外,您还可以配置应信任的代理标头

1->withMiddleware(function (Middleware $middleware) {
2 $middleware->trustProxies(headers: Request::HEADER_X_FORWARDED_FOR |
3 Request::HEADER_X_FORWARDED_HOST |
4 Request::HEADER_X_FORWARDED_PORT |
5 Request::HEADER_X_FORWARDED_PROTO |
6 Request::HEADER_X_FORWARDED_AWS_ELB
7 );
8})

如果您正在使用 AWS Elastic Load Balancing,则 headers 值应为 Request::HEADER_X_FORWARDED_AWS_ELB。如果您的负载均衡器使用来自 RFC 7239 的标准 Forwarded 标头,则 headers 值应为 Request::HEADER_FORWARDED。有关可在 headers 值中使用的常量的更多信息,请查看 Symfony 关于 信任代理 的文档。

信任所有代理

如果您正在使用 Amazon AWS 或其他“云”负载均衡器提供商,您可能不知道实际均衡器的 IP 地址。在这种情况下,您可以使用 * 来信任所有代理

1->withMiddleware(function (Middleware $middleware) {
2 $middleware->trustProxies(at: '*');
3})

配置受信任的主机

默认情况下,Laravel 将响应它收到的所有请求,而不管 HTTP 请求的 Host 标头的内容如何。此外,在 Web 请求期间生成应用程序的绝对 URL 时,将使用 Host 标头的值。

通常,您应该配置您的 Web 服务器(例如 Nginx 或 Apache)仅将与给定主机名匹配的请求发送到您的应用程序。但是,如果您无法直接自定义您的 Web 服务器,并且需要指示 Laravel 仅响应某些主机名,您可以通过为您的应用程序启用 Illuminate\Http\Middleware\TrustHosts 中间件来做到这一点。

要启用 TrustHosts 中间件,您应该在应用程序的 bootstrap/app.php 文件中调用 trustHosts 中间件方法。使用此方法的 at 参数,您可以指定您的应用程序应响应的主机名。来自其他 Host 标头的传入请求将被拒绝

1->withMiddleware(function (Middleware $middleware) {
2 $middleware->trustHosts(at: ['laravel.test']);
3})

默认情况下,来自应用程序 URL 子域的请求也会自动信任。如果您想禁用此行为,可以使用 subdomains 参数

1->withMiddleware(function (Middleware $middleware) {
2 $middleware->trustHosts(at: ['laravel.test'], subdomains: false);
3})

如果您需要访问应用程序的配置文件或数据库以确定受信任的主机,您可以为 at 参数提供一个闭包

1->withMiddleware(function (Middleware $middleware) {
2 $middleware->trustHosts(at: fn () => config('app.trusted_hosts'));
3})

Laravel 是构建、部署和监控软件的最有效方式。
构建、部署和监控软件。