HTTP 响应

创建响应

字符串与数组

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

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

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

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

INFO

你知道也可以从路由或控制器返回 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 头。指令应使用对应 cache-control 指令的「snake case」形式，并用分号分隔。若指令列表中指定了 etag，响应内容的 MD5 哈希会自动设置为 ETag 标识符：

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

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

向响应附加 Cookie

你可以使用 cookie 方法向即将发出的 Illuminate\Http\Response 实例附加 Cookie。应向该方法传入名称、值以及 Cookie 应视为有效的分钟数：

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

cookie 方法还接受一些较少使用的额外参数。一般而言，这些参数的用途和含义与 PHP 原生 setcookie 方法的参数相同：

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

若你希望确保 Cookie 随即将发出的响应一起发送，但尚未拥有该响应的实例，可以使用 Cookie Facade「排队」Cookie，以便在发送时附加到响应。queue 方法接受创建 Cookie 实例所需的参数。这些 Cookie 会在响应发送到浏览器之前附加到即将发出的响应上：

use Illuminate\Support\Facades\Cookie;

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

若希望生成可稍后附加到响应实例的 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 Facade 的 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 () {
    // Validate the request...

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

重定向到命名路由

不带参数调用 redirect 辅助函数时，会返回 Illuminate\Routing\Redirector 实例，使你可以在该 Redirector 实例上调用任何方法。例如，要生成指向命名路由的 RedirectResponse，可以使用 route 方法：

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

若路由有参数，可以将它们作为第二个参数传给 route 方法：

// For a route with the following URI: /profile/{id}

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

通过 Eloquent 模型填充参数

若你重定向到带有从 Eloquent 模型填充的「ID」参数的路由，可以直接传入该模型。ID 会自动提取：

// For a route with the following URI: /profile/{id}

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

若希望自定义放入路由参数的值，可以在路由参数定义中指定列（/profile/{id:slug}），或覆盖 Eloquent 模型上的 getRouteKey 方法：

php

/**
 * Get the value of the model's route key.
 */
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 方法实现，该方法会创建不进行额外 URL 编码、验证或校验的 RedirectResponse：

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">
        &#123;&#123; session('status') &#125;&#125;
    </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，并使用 PHP 的 json_encode 函数将给定数组转换为 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); // Simulate delay between chunks...
        }
    }, 200, ['X-Accel-Buffering' => 'no']);
});

INFO

在内部，Laravel 利用了 PHP 的输出缓冲功能。如上面的示例所示，你应使用 ob_flush 与 flush 函数将缓冲内容推送给客户端。

流式 JSON 响应

若需要增量流式传输 JSON 数据，可以使用 streamJson 方法。该方法特别适用于需要以易于 JavaScript 解析的格式逐步发送到浏览器的大型数据集：

use App\Models\User;

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

事件流

eventStream 方法可用于返回使用 text/event-stream 内容类型的服务器发送事件（SSE）流式响应。eventStream 方法接受一个闭包，该闭包应在响应可用时向流 yield 响应：

php

Route::get('/chat', function () {
    return response()->eventStream(function () {
        $stream = OpenAI::client()->chat()->createStreamed(...);

        foreach ($stream as $response) {
            yield $response->choices[0];
        }
    });
});

该事件流可由应用前端通过 EventSource 对象消费。流完成时，eventStream 方法会自动向事件流发送 </stream> 更新：

const source = new EventSource('/chat');

source.addEventListener('update', (event) => {
    if (event.data === '</stream>') {
        source.close();

        return;
    }

    console.log(event.data);
})

流式下载

有时你可能希望将某次操作的字符串响应转为可下载响应，而无需将操作内容写入磁盘。在这种场景下可以使用 streamDownload 方法。该方法接受回调、文件名以及可选的头数组作为参数：

use App\Services\GitHub;

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

响应宏

若希望定义可在多种路由和控制器中复用的自定义响应，可以在 Response Facade 上使用 macro 方法。通常应在应用的某个服务提供者（例如 App\Providers\AppServiceProvider）的 boot 方法中调用该方法：

php

<?php

namespace App\Providers;

use Illuminate\Support\Facades\Response;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Bootstrap any application services.
     */
    public function boot(): void
    {
        Response::macro('caps', function (string $value) {
            return Response::make(strtoupper($value));
        });
    }
}

macro 函数的第一个参数是名称，第二个参数是闭包。从 ResponseFactory 实现或 response 辅助函数调用该宏名称时，会执行宏的闭包：

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

HTTP 响应 ​

创建响应 ​

字符串与数组 ​

响应对象 ​

Eloquent 模型与集合 ​

向响应附加头 ​

缓存控制中间件 ​

向响应附加 Cookie ​

生成 Cookie 实例 ​

提前使 Cookie 过期 ​

Cookie 与加密 ​

重定向 ​

重定向到命名路由 ​

通过 Eloquent 模型填充参数 ​

重定向到控制器动作 ​

重定向到外部域名 ​

重定向并闪存会话数据 ​

重定向并携带输入 ​

其他响应类型 ​

视图响应 ​

JSON 响应 ​

文件下载 ​

文件响应 ​

流式响应 ​

流式 JSON 响应 ​

事件流 ​

流式下载 ​

响应宏 ​