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

缓存控制中间件

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

php

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 应被视为有效的分钟数：

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

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

php

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

重定向

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

php

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

有时你可能希望将用户重定向回其之前的页面，例如当提交的表单无效时。你可以通过使用全局 back 辅助函数来做到这一点。由于此功能利用了会话，请确保调用 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

// 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 方法：

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

带有闪现会话数据的重定向

重定向到一个新的 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，并使用 json_encode PHP 函数将给定数组转换为 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); // Simulate delay between chunks...
        }
    }, 200, ['X-Accel-Buffering' => 'no']);
});

为了方便起见，如果你提供给 stream 方法的闭包返回一个生成器，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 包：

bash

npm install @laravel/stream-react

bash

npm install @laravel/stream-vue

然后，useStream 可用于消费事件流。在提供了你的流 URL 后，该 hook 将自动更新 data 以随着你的 Laravel 应用返回内容而连接的响应：

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>

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

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

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

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>

onResponse 在流成功返回初始响应后触发，并且原始 [响应](https://developer.mozilla.org/en-US/docs/Web/API/Response) 会传递给回调函数。onData 会在接收到每个数据块时调用 - 当前数据块会传递给回调函数。onFinish 会在流完成时以及在抓取 / 读取周期中抛出错误时调用。

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

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>

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

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>

每当 useStream 钩子被使用时，会生成一个随机的 id 用于标识该流。此 id 会在每个请求中作为 X-STREAM-ID 头发送回服务器。当从多个组件消费同一个流时，您可以通过提供自己的 id 来读写该流：

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>

流式 JSON 响应

如果您需要增量传输 JSON 数据，可以使用 streamJson 方法。此方法对于需要以可由 JavaScript 轻松解析的格式逐步发送到浏览器的大型数据集特别有用：

php

use App\Models\User;

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

useJsonStream 钩子与 useStream 钩子等同，只是它会在完成流式传输后尝试将数据解析为 JSON:

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>

事件流 (SSE)

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

php

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

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

如果您想自定义事件的名称，您可以返回一个 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 包：

bash

npm install @laravel/stream-react

bash

npm install @laravel/stream-vue

然后，useEventStream 可用于消费事件流。在提供您的流 URL 后，该 hook 将自动使用串联的响应更新 message，因为消息会从您的 Laravel 应用程序返回：

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>

传入 useEventStream 的第二个参数是一个你可以用它来定制流的消费行为的选项对象。此对象的默认值如下所示：

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>

事件流也可以由你的应用程序前端通过一个 EventSource 对象手动消费。eventStream 方法会在流完成时，自动向事件流发送一个 </stream> 更新：

javascript

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

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

        return;
    }

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

为了自定义发送到事件流的最终事件，您可以提供一个 StreamedEvent 实例给 eventStream 方法的 endStreamWith 参数：

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
{
    /**
     * Bootstrap any application services.
     */
    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 模型和集合

附加头信息到响应

缓存控制中间件

附加 Cookie 到响应

生成 Cookie 实例

Cookies 提前过期

Cookie 和 加密

重定向

重定向到命名路由

通过 Eloquent 模型填充参数

重定向到控制器操作

重定向到外部域

带有闪现会话数据的重定向

带输入的重定向

其他响应类型

查看回复

JSON 响应

文件下载

文件响应

流式响应

消费流式响应

流式 JSON 响应

事件流 (SSE)

消费事件流

流式下载

响应宏

HTTP 响应

创建响应

字符串和数组

响应对象

Eloquent 模型和集合

附加头信息到响应

缓存控制中间件

附加 Cookie 到响应

生成 Cookie 实例

Cookies 提前过期

Cookie 和 加密

重定向

重定向到命名路由

通过 Eloquent 模型填充参数

重定向到控制器操作

重定向到外部域

带有闪现会话数据的重定向

带输入的重定向

其他响应类型

查看回复

JSON 响应

文件下载

文件响应

流式响应

消费流式响应

流式 JSON 响应

事件流 (SSE)

消费事件流

流式下载

响应宏

Cookie 和加密

Cookie 和加密