HTTP 响应

• 创建响应
  • 附加头到响应
  • 附加 Cookie 到响应
  • Cookie 和加密
• 重定向
  • 重定向到命名路由
  • 重定向到控制器操作
  • 重定向到外部域
  • 带闪存会话数据的重定向
• 其他响应类型
  • 视图响应
  • JSON 响应
  • 文件下载
  • 文件响应
• 流式响应
  • 消费流式响应
  • 流式 JSON 响应
  • 事件流 (SSE)
  • 流式下载
• 响应宏

创建响应

字符串和数组

所有路由和控制器都应返回要发送回用户浏览器的响应。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',
    ]);

您可以使用 withoutHeader 方法从传出响应中删除特定头：

return response($content)->withoutHeader('X-Debug');

return response($content)->withoutHeader(['X-Debug', 'X-Powered-By']);

缓存控制中间件

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

Route::middleware('cache.headers:public;max_age=30;s_maxage=300;stale_while_revalidate=600;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 方法的参数具有相同的用途和含义：

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): void {
    $middleware->encryptCookies(except: [
        'cookie_name',
    ]);
})

NOTE

通常，不应禁用 Cookie 加密，因为这会使您的 Cookie 面临潜在的客户端数据泄露和篡改风险。

重定向

重定向响应是 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 模型填充参数

如果您正在重定向到具有从 Eloquent 模型填充的"ID"参数的路由，可以传递模型本身。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 方法来实现，该方法创建一个不带任何额外 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">
        {{ 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);

流式响应

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

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

为方便起见，如果您提供给 stream 方法的闭包返回 Generator，Laravel 将自动在生成器返回的字符串之间刷新输出缓冲区，并禁用 Nginx 输出缓冲：

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

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

消费流式响应

可以使用 Laravel 的 stream npm 包消费流式响应，该包提供了与 Laravel 响应和事件流交互的便捷 API。首先，安装 @laravel/stream-react、@laravel/stream-vue 或 @laravel/stream-svelte 包：

npm install @laravel/stream-react

npm install @laravel/stream-vue

npm install @laravel/stream-svelte

然后，可以使用 useStream 来消费事件流。提供您的流 URL 后，钩子将随着 Laravel 应用程序返回内容自动更新 data：

import { useStream } from "@laravel/stream-react";

function App() {
    const { data, isFetching, isStreaming, send } = useStream("chat");

    const sendMessage = () => {
        send({
            message: `Current timestamp: ${Date.now()}`,
        });
    };

    return (
        <div>
            <div>{data}</div>
            {isFetching && <div>Connecting...</div>}
            {isStreaming && <div>Generating...</div>}
            <button onClick={sendMessage}>Send Message</button>
        </div>
    );
}

<script setup lang="ts">
import { useStream } from "@laravel/stream-vue";

const { data, isFetching, isStreaming, send } = useStream("chat");

const sendMessage = () => {
    send({
        message: `Current timestamp: ${Date.now()}`,
    });
};
</script>

<template>
    <div>
        <div>{{ data }}</div>
        <div v-if="isFetching">Connecting...</div>
        <div v-if="isStreaming">Generating...</div>
        <button @click="sendMessage">Send Message</button>
    </div>
</template>

<script>
import { useStream } from "@laravel/stream-svelte";

const stream = useStream("chat");

const sendMessage = () => {
    stream.send({
        message: `Current timestamp: ${Date.now()}`,
    });
};
</script>

<div>
    <div>{$stream.data}</div>
    {#if $stream.isFetching}
        <div>Connecting...</div>
    {/if}
    {#if $stream.isStreaming}
        <div>Generating...</div>
    {/if}
    <button onclick={sendMessage}>Send Message</button>
</div>

通过 send 发送数据回流时，在发送新数据之前会取消到流的活跃连接。所有请求都作为 JSON POST 请求发送。

WARNING

由于 useStream 钩子向您的应用程序发出 POST 请求，因此需要有效的 CSRF 令牌。提供 CSRF 令牌的最简单方法是通过应用程序布局头中的元标记包含它。

给 useStream 的第二个参数是一个选项对象，您可以使用它来自定义流消费行为。此对象的默认值如下所示：

import { useStream } from "@laravel/stream-react";

function App() {
    const { data } = useStream("chat", {
        id: undefined,
        initialInput: undefined,
        headers: undefined,
        csrfToken: undefined,
        onResponse: (response: Response) => void,
        onData: (data: string) => void,
        onCancel: () => void,
        onFinish: () => void,
        onError: (error: Error) => void,
    });

    return <div>{data}</div>;
}

<script setup lang="ts">
import { useStream } from "@laravel/stream-vue";

const { data } = useStream("chat", {
    id: undefined,
    initialInput: undefined,
    headers: undefined,
    csrfToken: undefined,
    onResponse: (response: Response) => void,
    onData: (data: string) => void,
    onCancel: () => void,
    onFinish: () => void,
    onError: (error: Error) => void,
});
</script>

<template>
    <div>{{ data }}</div>
</template>

<script>
import { useStream } from "@laravel/stream-svelte";

const stream = useStream("chat", {
    id: undefined,
    initialInput: undefined,
    headers: undefined,
    csrfToken: undefined,
    onResponse: (response) => {},
    onData: (data) => {},
    onCancel: () => {},
    onFinish: () => {},
    onError: (error) => {},
});
</script>

<div>{$stream.data}</div>