# HTTP 响应

-   [创建响应](#creating-responses)
    -   [将请求头附加到响应](#attaching-headers-to-responses)
    -   [将 Cookie 附加到响应](#attaching-cookies-to-responses)
    -   [Cookie 与加密](#cookies-and-encryption)
-   [重定向](#redirects)
    -   [重定向到命名路由](#redirecting-named-routes)
    -   [重定向到控制器动作](#redirecting-controller-actions)
    -   [重定向到外部域名](#redirecting-external-domains)
    -   [重定向并携带闪存 Session 数据](#redirecting-with-flashed-session-data)
-   [其他响应类型](#other-response-types)
    -   [视图响应](#view-responses)
    -   [JSON 响应](#json-responses)
    -   [文件下载](#file-downloads)
    -   [文件响应](#file-responses)
-   [流式响应](#streamed-responses)
    -   [消费流式响应](#consuming-streamed-responses)
    -   [流式 JSON 响应](#streamed-json-responses)
    -   [事件流（SSE）](#event-streams)
    -   [流式下载](#streamed-downloads)
-   [响应宏](#response-macros)

## 创建响应

#### 字符串和数组

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

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

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

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

> [!注意]
> 你知道吗，你也可以从路由或控制器返回 [Eloquent 集合](/docs/laravel/13.x/eloquent-collections)？它们会被自动转换为 JSON。试试看！

#### 响应对象

通常，你不会只从路由动作中返回简单的字符串或数组。相反，你会返回完整的 `Illuminate\Http\Response` 实例或 [视图](/docs/laravel/13.x/views)。



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

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

#### Eloquent 模型和集合

你也可以直接从路由和控制器返回 [Eloquent ORM](/docs/laravel/13.x/eloquent) 模型和集合。这样做时，Laravel 会自动将模型和集合转换为 JSON 响应，同时遵循模型的 [隐藏属性](/docs/laravel/13.x/eloquent-serialization#hiding-attributes-from-json) 设置：

```php
use App\Models\User;

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

### 将请求头附加到响应

请记住，大多数响应方法都可以链式调用，从而可以流畅地构建响应实例。例如，你可以使用 `header` 方法在将响应发送回用户之前，向响应添加一系列请求头：

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

或者，你可以使用 `withHeaders` 方法指定一个请求头数组，并将其添加到响应中：

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

你可以使用 `withoutHeader` 方法从即将发出的响应中移除指定请求头：

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

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

#### 缓存控制中间件



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

```php
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 的名称、值，以及该 Cookie 应被视为有效的分钟数：

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

`cookie` 方法还接受一些较少使用的额外参数。通常，这些参数与传递给 PHP 原生 [setcookie](https://secure.php.net/manual/en/function.setcookie.php) 方法的参数具有相同的用途和含义：

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

如果你想确保某个 Cookie 会随即将发出的响应一起发送，但你还没有该响应的实例，可以使用 `Cookie` 门面将 Cookie “排队”，以便在响应发送时附加到响应上。`queue` 方法接受创建 Cookie 实例所需的参数。这些 Cookie 会在即将发出的响应发送到浏览器之前被附加到响应上：

```php
use Illuminate\Support\Facades\Cookie;

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



#### 生成 Cookie 实例

如果你想生成一个 `Symfony\Component\HttpFoundation\Cookie` 实例，以便稍后将其附加到响应实例，可以使用全局 `cookie` 辅助函数。除非该 Cookie 被附加到响应实例，否则它不会被发送回客户端：

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

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

#### 提前使 Cookie 过期

你可以通过即将发出的响应的 `withoutCookie` 方法使 Cookie 过期，从而移除该 Cookie：

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

如果你还没有即将发出的响应实例，可以使用 `Cookie` 门面的 `expire` 方法使 Cookie 过期：

```php
Cookie::expire('name');
```

### Cookie 与加密

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

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

> [!注意]
> 通常，不应禁用 Cookie 加密，因为这会使你的 Cookie 面临潜在的客户端数据暴露和篡改风险。

## 重定向

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

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



有时你可能希望将用户重定向回他们之前的位置，例如提交的表单无效时。你可以使用全局 `back` 辅助函数来实现。由于此功能使用了 [session](/docs/laravel/13.x/session)，请确保调用 `back` 函数的路由正在使用 `web` 中间件组：

```php
Route::post('/user/profile', function () {
    // Validate the request...

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

### 重定向到命名路由

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

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

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

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

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

#### 通过 Eloquent 模型填充参数

如果你要重定向到一个带有“ID”参数的路由，而该参数是由 Eloquent 模型填充的，则可以传递模型本身。ID 会被自动提取：

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

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

如果你想自定义放入路由参数中的值，可以在路由参数定义中指定列（`/profile/{id:slug}`），或者可以在你的 Eloquent 模型上重写 `getRouteKey` 方法：

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



### 重定向到控制器动作

你也可以生成指向 [控制器动作](/docs/laravel/13.x/controllers) 的重定向。为此，请将控制器和动作名称传递给 `action` 方法：

```php
use App\Http\Controllers\UserController;

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

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

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

### 重定向到外部域名

有时你可能需要重定向到应用程序之外的域名。你可以通过调用 `away` 方法来实现，该方法会创建一个 `RedirectResponse`，不会进行任何额外的 URL 编码、验证或校验：

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

### 重定向并携带闪存 Session 数据

重定向到新的 URL 和 [将数据闪存到 session](/docs/laravel/13.x/session#flash-data) 通常会同时完成。通常，这是在成功执行某个操作后，将成功消息闪存到 session 中。为了方便起见，你可以创建一个 `RedirectResponse` 实例，并通过一个流畅的方法链将数据闪存到 session 中：

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

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

用户被重定向后，你可以从 [session](/docs/laravel/13.x/session) 中显示闪存消息。例如，使用 [Blade 语法](/docs/laravel/13.x/blade)：

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

#### 重定向并携带输入



您可以使用 `RedirectResponse` 实例提供的 `withInput` 方法，在将用户重定向到新位置之前，将当前请求的输入数据闪存（flash）到会话中。如果用户遇到了验证错误，通常会这样做。一旦输入数据被闪存到会话中，您可以在下一次请求期间轻松地[获取它](/docs/laravel/13.x/requests#retrieving-old-input)，以重新填充表单：

```php
return back()->withInput();
```

## 其他响应类型

`response` 辅助函数可用于生成其他类型的响应实例。当调用 `response` 辅助函数时不传递参数，将返回 `Illuminate\Contracts\Routing\ResponseFactory` [契约](/docs/laravel/13.x/contracts) 的一个实现。该契约提供了多个用于生成响应的便捷方法。

### 视图响应

如果您需要控制响应的状态码和请求头，同时还需要返回一个作为响应内容的[视图](/docs/laravel/13.x/views)，则应该使用 `view` 方法：

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

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

### JSON 响应

`json` 方法会自动将 `Content-Type` 请求头设置为 `application/json`，同时使用 PHP 的 `json_encode` 函数将给定数组转换为 JSON：

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

如果您希望创建 JSONP 响应，可以将 `json` 方法与 `withCallback` 方法结合使用：

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



### 文件下载

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

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

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

> [!警告]
> 管理文件下载的 Symfony HttpFoundation 要求被下载文件必须具有 ASCII 文件名。

### 文件响应

`file` 方法可用于直接在用户的浏览器中显示文件，例如图片或 PDF，而不是触发下载。该方法接受文件的绝对路径作为第一个参数，并接受请求头数组作为第二个参数：

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

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

## 流式响应

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


```php
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](https://www.php.net/manual/en/language.generators.overview.php)，Laravel 将自动在生成器返回的字符串之间刷新输出缓冲区，同时禁用 Nginx 输出缓冲：

```php
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 包来消费流式响应，该包提供了一个便捷的 API，用于与 Laravel 响应流和事件流进行交互。开始使用前，请安装 `@laravel/stream-react`、`@laravel/stream-vue` 或 `@laravel/stream-svelte` 包：

```shell tab=React
npm install @laravel/stream-react
```

```shell tab=Vue
npm install @laravel/stream-vue
```

```shell tab=Svelte
npm install @laravel/stream-svelte
```

然后，可以使用 `useStream` 来消费事件流。提供流 URL 后，该 Hook 会自动更新 `data`，并将从 Laravel 应用返回的内容拼接为完整响应：

```tsx tab=React
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>
    );
}
```

```vue tab=Vue
<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>
```

```svelte tab=Svelte
<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` 请求的形式发送。

> [!警告]
> 由于 `useStream` Hook 会向您的应用程序发起 `POST` 请求，因此需要有效的 CSRF 令牌。提供 CSRF 令牌最简单的方法是[通过 meta 标签将其包含在应用布局的 head 部分中](/docs/laravel/13.x/csrf#csrf-x-csrf-token)。



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

```tsx tab=React
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>;
}
```

```vue tab=Vue
<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>
```

```svelte tab=Svelte
<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>
```

`onResponse` 会在流首次成功响应后触发，并将原始的 [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) 传递给回调函数。`onData` 会在每个数据块接收时被调用，当前数据块会传递给回调函数。`onFinish` 会在流结束时调用，以及在 fetch / read 周期中抛出错误时调用。

默认情况下，初始化时不会向流发起请求。您可以通过使用 `initialInput` 选项向流传递初始数据：

```tsx tab=React
import { useStream } from "@laravel/stream-react";

function App() {
    const { data } = useStream("chat", {
        initialInput: {
            message: "Introduce yourself.",
        },
    });

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

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

const { data } = useStream("chat", {
    initialInput: {
        message: "Introduce yourself.",
    },
});
</script>

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

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

const stream = useStream("chat", {
    initialInput: {
        message: "Introduce yourself.",
    },
});
</script>

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



要手动取消流，可以使用 Hook 返回的 `cancel` 方法：

```tsx tab=React
import { useStream } from "@laravel/stream-react";

function App() {
    const { data, cancel } = useStream("chat");

    return (
        <div>
            <div>{data}</div>
            <button onClick={cancel}>Cancel</button>
        </div>
    );
}
```

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

const { data, cancel } = useStream("chat");
</script>

<template>
    <div>
        <div>{{ data }}</div>
        <button @click="cancel">Cancel</button>
    </div>
</template>
```

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

const stream = useStream("chat");
</script>

<div>
    <div>{$stream.data}</div>
    <button onclick={() => stream.cancel()}>Cancel</button>
</div>
```

每次使用 `useStream` Hook 时，都会生成一个随机 `id` 来标识该流。该 `id` 会通过 `X-STREAM-ID` 请求头随每次请求发送回服务器。当需要在多个组件中消费同一个流时，可以通过提供自己的 `id` 来读取和写入流：

```tsx tab=React
// App.tsx
import { useStream } from "@laravel/stream-react";

function App() {
    const { data, id } = useStream("chat");

    return (
        <div>
            <div>{data}</div>
            <StreamStatus id={id} />
        </div>
    );
}

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

function StreamStatus({ id }) {
    const { isFetching, isStreaming } = useStream("chat", { id });

    return (
        <div>
            {isFetching && <div>Connecting...</div>}
            {isStreaming && <div>Generating...</div>}
        </div>
    );
}
```

```vue tab=Vue
<!-- App.vue -->
<script setup lang="ts">
import { useStream } from "@laravel/stream-vue";
import StreamStatus from "./StreamStatus.vue";

const { data, id } = useStream("chat");
</script>

<template>
    <div>
        <div>{{ data }}</div>
        <StreamStatus :id="id" />
    </div>
</template>

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

const props = defineProps<{
    id: string;
}>();

const { isFetching, isStreaming } = useStream("chat", { id: props.id });
</script>

<template>
    <div>
        <div v-if="isFetching">Connecting...</div>
        <div v-if="isStreaming">Generating...</div>
    </div>
</template>
```

```svelte tab=Svelte
<!-- App.svelte -->
<script>
import { useStream } from "@laravel/stream-svelte";
import StreamStatus from "./StreamStatus.svelte";

const stream = useStream("chat");
</script>

<div>
    <div>{$stream.data}</div>
    <StreamStatus id={stream.id} />
</div>

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

let { id } = $props();

const stream = useStream("chat", { id });
</script>

<div>
    {#if $stream.isFetching}
        <div>Connecting...</div>
    {/if}
    {#if $stream.isStreaming}
        <div>Generating...</div>
    {/if}
</div>
```



### 流式 JSON 响应

如果你需要增量地流式传输 JSON 数据，可以使用 `streamJson` 方法。该方法特别适用于需要逐步发送到浏览器，并且可以被 JavaScript 轻松解析的大型数据集：

```php
use App\Models\User;

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

`useJsonStream` 钩子与 [useStream 钩子](#consuming-streamed-responses) 完全相同，只不过它会在数据流传输完成后，尝试将数据解析为 JSON：

```tsx tab=React
import { useJsonStream } from "@laravel/stream-react";

type User = {
    id: number;
    name: string;
    email: string;
};

function App() {
    const { data, send } = useJsonStream<{ users: User[] }>("users");

    const loadUsers = () => {
        send({
            query: "taylor",
        });
    };

    return (
        <div>
            <ul>
                {data?.users.map((user) => (
                    <li>
                        {user.id}: {user.name}
                    </li>
                ))}
            </ul>
            <button onClick={loadUsers}>Load Users</button>
        </div>
    );
}
```

```vue tab=Vue
<script setup lang="ts">
import { useJsonStream } from "@laravel/stream-vue";

type User = {
    id: number;
    name: string;
    email: string;
};

const { data, send } = useJsonStream<{ users: User[] }>("users");

const loadUsers = () => {
    send({
        query: "taylor",
    });
};
</script>

<template>
    <div>
        <ul>
            <li v-for="user in data?.users" :key="user.id">
                {{ user.id }}: {{ user.name }}
            </li>
        </ul>
        <button @click="loadUsers">Load Users</button>
    </div>
</template>
```

```svelte tab=Svelte
<script>
import { useJsonStream } from "@laravel/stream-svelte";

const stream = useJsonStream("users");

const loadUsers = () => {
    stream.send({
        query: "taylor",
    });
};
</script>

<div>
    <ul>
        {#if $stream.data?.users}
            {#each $stream.data.users as user (user.id)}
                <li>{user.id}: {user.name}</li>
            {/each}
        {/if}
    </ul>
    <button onclick={loadUsers}>Load Users</button>
</div>
```



### 事件流（SSE）

`eventStream` 方法可用于使用 `text/event-stream` 内容类型返回服务器发送事件（SSE）流式响应。`eventStream` 方法接收一个闭包，该闭包应该在响应可用时，通过 [yield](https://www.php.net/manual/en/language.generators.overview.php) 将响应流返回：

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

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

如果你希望自定义事件名称，可以 yield 一个 `StreamedEvent` 类的实例：

```php
use Illuminate\Http\StreamedEvent;

yield new StreamedEvent(
    event: 'update',
    data: $response->choices[0],
);
```

#### 消费事件流

事件流可以使用 Laravel 的 `stream` npm 包进行消费，该包提供了一个方便的 API，用于与 Laravel 事件流进行交互。开始使用前，请安装 `@laravel/stream-react`、`@laravel/stream-vue` 或 `@laravel/stream-svelte` 包：


```shell tab=React
npm install @laravel/stream-react
```

```shell tab=Vue
npm install @laravel/stream-vue
```

```shell tab=Svelte
npm install @laravel/stream-svelte
```

然后，可以使用 `useEventStream` 来消费事件流。在提供你的流 URL 后，该钩子会自动更新 `message`，并将从你的 Laravel 应用返回的消息拼接成完整响应：

```jsx tab=React
import { useEventStream } from "@laravel/stream-react";

function App() {
  const { message } = useEventStream("/chat");

  return <div>{message}</div>;
}
```

```vue tab=Vue
<script setup lang="ts">
import { useEventStream } from "@laravel/stream-vue";

const { message } = useEventStream("/chat");
</script>

<template>
  <div>{{ message }}</div>
</template>
```

```svelte tab=Svelte
<script>
import { useEventStream } from "@laravel/stream-svelte";

const eventStream = useEventStream("/chat");
</script>

<div>{$eventStream.message}</div>
```



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

```jsx tab=React
import { useEventStream } from "@laravel/stream-react";

function App() {
  const { message } = useEventStream("/stream", {
    eventName: "update",
    onMessage: (message) => {
      //
    },
    onError: (error) => {
      //
    },
    onComplete: () => {
      //
    },
    endSignal: "</stream>",
    glue: " ",
  });

  return <div>{message}</div>;
}
```

```vue tab=Vue
<script setup lang="ts">
import { useEventStream } from "@laravel/stream-vue";

const { message } = useEventStream("/chat", {
  eventName: "update",
  onMessage: (message) => {
    // ...
  },
  onError: (error) => {
    // ...
  },
  onComplete: () => {
    // ...
  },
  endSignal: "</stream>",
  glue: " ",
});
</script>
```

```svelte tab=Svelte
<script>
import { useEventStream } from "@laravel/stream-svelte";

const eventStream = useEventStream("/chat", {
    eventName: "update",
    onMessage: (event) => {
        //
    },
    onError: (error) => {
        //
    },
    onComplete: () => {
        //
    },
    endSignal: "</stream>",
    glue: " ",
    replace: false,
});
</script>
```

事件流也可以通过应用程序前端的 [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) 对象手动消费。当流完成时，`eventStream` 方法会自动向事件流发送一个 `</stream>` 更新：

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

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

        return;
    }

    console.log(event.data);
});
```

要自定义发送到事件流中的最终事件，可以向 `eventStream` 方法的 `endStreamWith` 参数提供一个 `StreamedEvent` 实例：

```php
return response()->eventStream(function () {
    // ...
}, endStreamWith: new StreamedEvent(event: 'update', data: '</stream>'));
```


### 流式下载

有时，你可能希望将某个操作返回的字符串响应转换为可下载的响应，而无需将该操作的内容写入磁盘。在这种情况下，可以使用 `streamDownload` 方法。该方法接收一个回调函数、文件名以及可选的请求头数组作为参数：

```php
use App\Services\GitHub;

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



## 响应宏
如果你希望定义一个可以在多个路由和控制器中重复使用的自定义响应，可以使用 `Response` 门面上的 `macro` 方法。通常，你应该在应用程序某个[服务提供者](/docs/laravel/13.x/providers)的 `boot` 方法中调用此方法，例如 `App\Providers\AppServiceProvider` 服务提供者：

```php
<?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` 辅助函数中调用宏名称时，宏的闭包将会被执行：

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