响应

创建响应

字符串与数组

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

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

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

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

你知道吗，你也可以从路由或控制器中返回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，则会自动将响应内容的 xxh128 哈希值设置为 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 方法向即将发出的 Illuminate\Http\Response 实例附加一个 Cookie。你应将 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 门面将 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 或 withoutCookies 方法使 Cookie 过期，从而将其移除：

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

return response('Hello World')->withoutCookies([
    'name',
    'email',
    'preferences',
]);

如果你尚未拥有即将发出的响应实例，可以使用 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',
    ]);
})

一般而言，永远不应禁用 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 模型填充参数

如果你要重定向到一个带有“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，并使用 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'));

Markdown 响应

可以使用 markdown 方法返回 Markdown 内容，并将 Content-Type 头部设置为 text/markdown：

return response()->markdown("# Hello\n\nWorld");

你可以将自定义的 HTTP 状态码和额外的头部数组作为第二个和第三个参数传入：

return response()->markdown('# Not Found', 404, ['X-Custom-Header' => 'Value']);

文件下载

可以使用 download 方法生成一个响应，强制用户的浏览器下载给定路径的文件。download 方法将文件名作为该方法的第二个参数，这将决定下载文件的用户所看到的文件名。最后，你可以将 HTTP 头部数组作为该方法的第三个参数传入：

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

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

管理文件下载的 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 方法的闭包返回一个生成器，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>

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

由于 useStream 钩子会向你的应用发起 POST 请求，因此需要一个有效的 CSRF 令牌。提供 CSRF 令牌的最简便方式是通过应用布局头部的 meta 标签将其包含进去。

传递给 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>

onResponse 会在流返回成功的初始响应之后触发，原始的Response会被传递给回调函数。每接收到一个数据块时会调用 onData——当前数据块会被传递给回调函数。当流结束以及在 fetch / 读取周期中抛出错误时会调用 onFinish。

默认情况下，初始化时不会向流发起请求。你可以使用 initialInput 选项向流传递初始负载：

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

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

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

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

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

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

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

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

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

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

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

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

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

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

<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 来读取和写入该流：

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

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

流式 JSON 响应

如果你需要以增量方式流式传输 JSON 数据，可以使用 streamJson 方法。对于需要逐步发送到浏览器、且能被 JavaScript 轻松解析格式的大型数据集而言，该方法尤为实用：

use App\Models\User;

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

useJsonStream 钩子与 useStream 钩子完全一致，唯一不同的是，它会在流式传输完成后尝试将数据解析为 JSON：

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

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

事件流（SSE）

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

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

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

如果你想自定义事件的名称，可以生成 StreamedEvent 类的实例：

use Illuminate\Http\StreamedEvent;

yield new StreamedEvent(
    event: 'update',
    data: $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

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

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

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

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

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

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

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

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

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

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

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

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

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

<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 实例：

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

流式下载

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

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