HTTP 响应 – 乌鸦嘴文档中心

创建响应

字符串和数组

所有路由和控制器都应返回一个响应，以发送回用户的浏览器。Laravel 提供了几种不同的方式来返回响应。最基本的响应是从路由或控制器返回一个字符串。框架会自动将该字符串转换为完整的 HTTP 响应：

Route::get('/', function () {
    return 'Hello World';
});

除了从您的路由和控制器返回字符串外，您还可以返回数组。框架会自动将数组转换为 JSON 响应：

Route::get('/', function () {
    return [1, 2, 3];
});

[!NOTE]
您知道您还可以从您的路由或控制器返回Eloquent 集合吗？它们将自动转换为 JSON。试试看！

响应对象

通常，您不会仅仅从您的路由操作中返回简单的字符串或数组。相反，您将返回完整的Illuminate\Http\Response实例或视图。

返回完整的Response实例允许您自定义响应的 HTTP 状态代码和标头。Response实例继承自Symfony\Component\HttpFoundation\Response类，该类提供了多种构建 HTTP 响应的方法：

Route::get('/home', function () {
    return response('Hello World', 200)
                  ->header('Content-Type', 'text/plain');
});

Eloquent 模型和集合

您还可以直接从您的路由和控制器返回Eloquent ORM模型和集合。当您这样做时，Laravel 会在尊重模型的隐藏属性的同时，自动将模型和集合转换为 JSON 响应：

use App\Models\User;

Route::get('/user/{user}', function (User $user) {
    return $user;
});

为响应附加标头

请记住，大多数响应方法是可链式调用的，允许流畅地构建响应实例。例如，您可以使用header方法在将响应发送回用户之前向响应添加一系列标头：

return response($content)
            ->header('Content-Type', $type)
            ->header('X-Header-One', 'Header Value')
            ->header('X-Header-Two', 'Header Value');

或者，您可以使用withHeaders方法指定要添加到响应的标头数组：

return response($content)
            ->withHeaders([
                'Content-Type' => $type,
                'X-Header-One' => 'Header Value',
                'X-Header-Two' => 'Header Value',
            ]);

缓存控制中间件

Laravel 包含一个cache.headers中间件，可用于快速为一组路由设置Cache-Control标头。指令应使用相应缓存控制指令的“蛇形命名法”等效形式提供，并应以分号分隔。如果在指令列表中指定了etag，则响应内容的 MD5 哈希将自动设置为 ETag 标识符：

Route::middleware('cache.headers:public;max_age=2628000;etag')->group(function () {
    Route::get('/privacy', function () {
        //...
    });

    Route::get('/terms', function () {
        //...
    });
});

为响应附加 Cookie

您可以使用cookie方法将 Cookie 附加到传出的Illuminate\Http\Response实例。您应该将名称、值以及 Cookie 应被视为有效的分钟数传递给此方法：

return response('Hello World')->cookie(
    'name', 'value', $minutes
);

cookie方法还接受一些不太常用的其他参数。通常，这些参数的目的和含义与 PHP 原生的setcookie (opens in a new tab)方法的参数相同：

return response('Hello World')->cookie(
    'name', 'value', $minutes, $path, $domain, $secure, $httpOnly
);

如果您希望确保 Cookie 随传出响应一起发送，但您尚未拥有该响应的实例，则可以使用Cookie外观来“排队”Cookie，以便在发送响应时将其附加到响应上。queue方法接受创建 Cookie 实例所需的参数。这些 Cookie 将在将传出响应发送到浏览器之前附加到该响应上：

use Illuminate\Support\Facades\Cookie;

Cookie::queue('name', 'value', $minutes);

生成 Cookie 实例

如果您想要生成一个 Symfony\Component\HttpFoundation\Cookie 实例，以便稍后可以将其附加到响应实例上，您可以使用全局的 cookie 助手。除非将此 Cookie 附加到响应实例上，否则它不会发送回客户端：

$cookie = cookie('name', 'value', $minutes);

return response('Hello World')->cookie($cookie);

提前使 Cookie 过期

您可以通过对传出响应的 withoutCookie 方法使 Cookie 过期来删除它：

return response('Hello World')->withoutCookie('name');

如果您还没有传出响应的实例，您可以使用 Cookie 外观的 expire 方法来使 Cookie 过期：

Cookie::expire('name');

Cookie 与加密

默认情况下，由于 Illuminate\Cookie\Middleware\EncryptCookies 中间件的存在，Laravel 生成的所有 Cookie 都经过加密和签名，因此客户端无法修改或读取它们。如果您希望为应用程序生成的一部分 Cookie 禁用加密，您可以在应用程序的 bootstrap/app.php 文件中使用 encryptCookies 方法：

->withMiddleware(function (Middleware $middleware) {
    $middleware->encryptCookies(except: [
        'cookie_name',
    ]);
})

重定向

重定向响应是 Illuminate\Http\RedirectResponse 类的实例，并包含将用户重定向到另一个 URL 所需的正确标头。有几种方法可以生成 RedirectResponse 实例。最简单的方法是使用全局的 redirect 助手：

Route::get('/dashboard', function () {
    return redirect('/home/dashboard');
});

有时您可能希望将用户重定向到他们之前的位置，例如当提交的表单无效时。您可以使用全局的 back 助手函数来实现。由于此功能利用了会话，请确保调用 back 函数的路由正在使用 web 中间件组：

Route::post('/user/profile', function () {
    // 验证请求...

    return back()->withInput();
});

重定向到命名路由

当您调用不带参数的 redirect 助手时，将返回一个 Illuminate\Routing\Redirector 的实例，允许您在 Redirector 实例上调用任何方法。例如，要生成一个重定向到命名路由的 RedirectResponse，您可以使用 route 方法：

return redirect()->route('login');

如果您的路由有参数，您可以将它们作为 route 方法的第二个参数传递：

// 对于具有以下 URI 的路由：/profile/{id}

return redirect()->route('profile', ['id' => 1]);

通过 Eloquent 模型填充参数

如果您要重定向到一个路由，其中的“ID”参数是从 Eloquent 模型中填充的，您可以传递模型本身。ID 将自动提取：

// 对于具有以下 URI 的路由：/profile/{id}

return redirect()->route('profile', [$user]);

如果您想要自定义放置在路由参数中的值，您可以在路由参数定义中指定列（/profile/{id:slug}），或者您可以在您的 Eloquent 模型上覆盖 getRouteKey 方法：

/**
 * 获取模型路由键的值。
 */
public function getRouteKey(): mixed
{
    return $this->slug;
}

重定向到控制器操作

您也可以生成重定向到控制器操作。为此，将控制器和操作名称传递给 action 方法：

use App\Http\Controllers\UserController;

return redirect()->action([UserController::class, 'index']);

如果您的控制器路由需要参数，您可以将它们作为 action 方法的第二个参数传递：

return redirect()->action(
    [UserController::class, 'profile'], ['id' => 1]
);

重定向到外部域

有时您可能需要重定向到应用程序外部的域。您可以通过调用 away 方法来实现，该方法创建一个 RedirectResponse，而无需任何额外的 URL 编码、验证或验证：

return redirect()->away('https://www.google.com');

带有闪存会话数据的重定向

重定向到新的 URL 并将会话数据闪存到会话中通常是同时进行的。通常，这是在成功执行操作后完成的，例如当您将会话闪存一个成功消息时。为了方便起见，您可以创建一个 RedirectResponse 实例，并在一个流畅的方法链中将会话数据闪存到会话中：

Route::post('/user/profile', function () {
    //...

    return redirect('/dashboard')->with('status', 'Profile updated!');
});

在用户被重定向后，您可以从会话中显示闪存消息。例如，使用 Blade 语法：

@if (session('status'))
    <div class="alert alert-success">
        {{ session('status') }}
    </div>
@endif

带有输入的重定向

您可以使用 RedirectResponse 实例提供的 withInput 方法，在将用户重定向到新位置之前，将会话的当前请求输入数据闪存到会话中。这通常在用户遇到验证错误时完成。一旦将输入闪存到会话中，您可以在下次请求期间轻松地检索它以重新填充表单：

return back()->withInput();

其他响应类型

response 助手函数可用于生成其他类型的响应实例。当不带参数调用 response 助手函数时，将返回 Illuminate\Contracts\Routing\ResponseFactory 契约的一个实现。该契约提供了几个用于生成响应的有用方法。

视图响应

如果您需要控制响应的状态和标头，同时需要将视图作为响应的内容返回，则应使用 view 方法：

return response()
            ->view('hello', $data, 200)
            ->header('Content-Type', $type);

当然，如果您不需要传递自定义的 HTTP 状态码或自定义标头，则可以使用全局的 view 助手函数。

JSON 响应

json 方法将自动将 Content-Type 标头设置为 application/json，并使用 json_encode PHP 函数将给定的数组转换为 JSON：

return response()->json([
    'name' => 'Abigail',
    'state' => 'CA',
]);

如果您想要创建一个 JSONP 响应，可以将 json 方法与 withCallback 方法结合使用：

return response()
            ->json(['name' => 'Abigail', 'state' => 'CA'])
            ->withCallback($request->input('callback'));

文件下载

download 方法可用于生成一个响应，强制用户的浏览器下载给定路径的文件。download 方法接受文件名作为该方法的第二个参数，该文件名将决定用户下载文件时看到的文件名。最后，您可以将一个 HTTP 标头数组作为该方法的第三个参数传递：

return response()->download($pathToFile);

return response()->download($pathToFile, $name, $headers);

[!WARNING]
管理文件下载的 Symfony HttpFoundation 要求被下载的文件具有 ASCII 文件名。

文件响应

file 方法可用于在用户的浏览器中直接显示文件，例如图像或 PDF，而不是启动下载。该方法接受文件的绝对路径作为其第一个参数，以及一个标头数组作为其第二个参数：

return response()->file($pathToFile);

return response()->file($pathToFile, $headers);

流式响应

通过在生成数据时将其流式传输到客户端，您可以显著减少内存使用并提高性能，特别是对于非常大的响应。流式响应允许客户端在服务器完成发送之前开始处理数据：

function streamedContent(): Generator {
    yield 'Hello, ';
    yield 'World!';
}
 
Route::get('/stream', function () {
    return response()->stream(function (): void {
        foreach (streamedContent() as $chunk) {
            echo $chunk;
            ob_flush();
            flush();
            sleep(2); // 模拟块之间的延迟...
        }
    }, 200, ['X-Accel-Buffering' => 'no']);
});

[!NOTE] 在内部，Laravel 利用 PHP 的输出缓冲功能。如您在上面的示例中所见，您应该使用 ob_flush 和 flush 函数将缓冲的内容推送到客户端。

流式 JSON 响应

如果您需要逐步流式传输 JSON 数据，可以使用 streamJson 方法。此方法对于需要以可由 JavaScript 轻松解析的格式逐步发送到浏览器的大型数据集特别有用：

use App\Models\User;
 
Route::get('/users.json', function () {
    return response()->streamJson([
        'users' => User::cursor(),
    ]);
});

流式下载

有时，您可能希望将给定操作的字符串响应转换为可下载的响应，而无需将操作的内容写入磁盘。在这种情况下，您可以使用 streamDownload 方法。该方法接受一个回调函数、文件名和一个可选的标头数组作为其参数：

use App\Services\GitHub;
 
return response()->streamDownload(function () {
    echo GitHub::api('repo')
                ->contents()
                ->readme('laravel', 'laravel')['contents'];
}, 'laravel-readme.md');

响应宏

如果您想要定义一个可以在各种路由和控制器中重复使用的自定义响应，可以在 Response 外观上使用 macro 方法。通常，您应该从应用程序的服务提供者（例如 App\Providers\AppServiceProvider 服务提供者）的 boot 方法中调用此方法：

<?php
 
namespace App\Providers;
 
use Illuminate\Support\Facades\Response;
use Illuminate\Support\ServiceProvider;
 
class AppServiceProvider extends ServiceProvider
{
    /**
     * 启动任何应用程序服务。
     */
    public function boot(): void
    {
        Response::macro('caps', function (string $value) {
            return Response::make(strtoupper($value));
        });
    }
}

macro 函数接受一个名称作为其第一个参数，一个闭包作为其第二个参数。当从 ResponseFactory 实现或 response 助手函数中调用宏名称时，将执行宏的闭包：

return response()->caps('foo');

HTTP 请求视图