HTTP 响应

创建响应
重定向
其他响应类型
流式响应
响应宏

创建响应

字符串与数组

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

php

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

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

php

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

NOTE

您知道也可以从路由或控制器返回 Eloquent 集合吗？它们会自动转换为 JSON。试试看！

响应对象

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

返回完整的 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 模型和集合。当您这样做时，Laravel 会自动将模型和集合转换为 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 头。指令应使用相应缓存控制指令的“蛇形命名法”提供，并用分号分隔。如果在指令列表中指定了 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 () {
        // ...
    });
});

向响应附加 Cookies

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

php

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

cookie 方法也接受一些较少使用的额外参数。通常，这些参数具有与 PHP 原生 setcookie 方法相同的用途和含义：

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);

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

php

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

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

提前使 Cookies 过期

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

php

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

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

php

Cookie::expire('name');

Cookies 与加密

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

php

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

NOTE

通常，绝不应禁用 cookie 加密，因为这会暴露您的 cookie，使其可能被客户端数据泄露和篡改。

重定向

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

php

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

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

php

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

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

重定向到命名路由

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

php

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

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

php

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

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

通过 Eloquent 模型填充参数

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

php

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

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

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

php

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

重定向到控制器动作

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

php

use App\Http\Controllers\UserController;

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

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

php

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

重定向到外部域名

有时您可能需要重定向到应用程序外部的域名。您可以通过调用 away 方法来做到这一点，它会创建一个没有任何额外 URL 编码、验证或检查的 RedirectResponse：

php

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

重定向并闪存会话数据

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

php

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

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

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

blade

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

重定向并附带输入

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

php

return back()->withInput();

其他响应类型

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

视图响应

如果您需要控制响应的状态和头信息，但也需要返回一个视图作为响应的内容，您应该使用 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);

WARNING

管理文件下载的 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，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 包：

ReactVueSvelte

shell

npm install @laravel/stream-react

shell

npm install @laravel/stream-vue

shell

npm install @laravel/stream-svelte

然后，可以使用 useStream 来消费事件流。提供您的流 URL 后，该钩子将自动更新 data，因为内容从您的 Laravel 应用程序返回时会被连接起来：

ReactVueSvelte

tsx

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

<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

<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 令牌的最简单方法是在应用程序布局的头部通过 meta 标签包含它。

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

ReactVueSvelte

tsx

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

<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

<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 被传递给回调。onData 在接收到每个块时调用 - 当前块被传递给回调。onFinish 在流完成时以及在获取/读取周期中抛出错误时调用。

默认情况下，初始化时不会向流发出请求。您可以通过使用 initialInput 选项将初始负载传递给流：

ReactVueSvelte

tsx

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

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

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

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

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

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

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

要手动取消流，您可以使用钩子返回的 cancel 方法：

ReactVueSvelte

tsx

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

<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

<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 钩子时，都会生成一个随机 id 来标识流。这个 id 会随着每个请求在 X-STREAM-ID 头中发送回服务器。当从多个组件消费同一个流时，您可以通过提供自己的 id 来读写流：

ReactVueSvelte

tsx

// 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

<!-- 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

<!-- 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 钩子相同，只是它会在流完成后尝试将数据解析为 JSON：

ReactVueSvelte

tsx

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

<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

<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 到流中：

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 包：

ReactVueSvelte

shell

npm install @laravel/stream-react

shell

npm install @laravel/stream-vue

shell

npm install @laravel/stream-svelte

然后，可以使用 useEventStream 来消费事件流。提供您的流 URL 后，当消息从您的 Laravel 应用程序返回时，该钩子将自动更新 message，因为消息被连接起来：

ReactVueSvelte

jsx

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

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

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

vue

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

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

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

svelte

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

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

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

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

ReactVueSvelte

jsx

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

<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

<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 对象手动消费。eventStream 方法将在流完成时自动向事件流发送一个 </stream> 更新：

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 方法。通常，您应该从应用程序的某个服务提供者的 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');

HTTP 响应 ​

创建响应 ​

字符串与数组 ​

响应对象 ​

Eloquent 模型与集合 ​

向响应附加头信息 ​

缓存控制中间件 ​

向响应附加 Cookies ​

生成 Cookie 实例 ​

提前使 Cookies 过期 ​

Cookies 与加密 ​

重定向 ​

重定向到命名路由 ​

通过 Eloquent 模型填充参数 ​

重定向到控制器动作 ​

重定向到外部域名 ​

重定向并闪存会话数据 ​

重定向并附带输入 ​

其他响应类型 ​

视图响应 ​

JSON 响应 ​

文件下载 ​

文件响应 ​

流式响应 ​

消费流式响应 ​

流式 JSON 响应 ​

事件流 (SSE) ​

消费事件流 ​

流式下载 ​

响应宏 ​

HTTP 响应

创建响应

字符串与数组

响应对象

Eloquent 模型与集合

向响应附加头信息

缓存控制中间件

向响应附加 Cookies

生成 Cookie 实例

提前使 Cookies 过期

Cookies 与加密

重定向

重定向到命名路由

通过 Eloquent 模型填充参数

重定向到控制器动作

重定向到外部域名

重定向并闪存会话数据

重定向并附带输入

其他响应类型

视图响应

JSON 响应

文件下载

文件响应

流式响应

消费流式响应

流式 JSON 响应

事件流 (SSE)

消费事件流

流式下载

响应宏