HTTP 响应

创建响应

字符串和数组

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

php

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

除了从 routes 和 controller 返回字符串外，您还可以返回数组。框架会自动将数组转换为 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 方法在将响应发送回给用户之前向响应中添加一系列 headers：

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 标头。指令应使用相当于相应 cache-control 指令的“snake case”来提供，并且应该用分号分隔。如果在指令列表中指定了 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 实例。您应该将 name （名称）、值（value）和 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 Facade将 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);

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

php

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

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

php

    Cookie::expire('name');

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

php

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

重定向

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

php

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

有时，您可能希望将用户重定向到他们之前的位置，例如当提交的表单无效时。您可以使用全局 back helper 函数来执行此操作。由于此功能利用了 session，因此请确保调用 back 函数的路由正在使用 Web 中间件组：

php

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

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

重定向到命名路由

当您调用不带参数的重定向帮助程序时，将返回 Illuminate\Routing\Redirector 的实例，允许您调用 Redirector 实例上的任何方法。例如，要生成命名路由的 RedirectResponse，你可以使用 route 方法：

php

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

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

php

    // 对于具有以下 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

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

重定向到 Controller 操作

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

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 实例，并在单个 Fluent 方法链中将数据闪存到 session：

php

    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 方法将当前请求的输入数据刷入会话。如果用户遇到验证错误，通常会执行此操作。一旦输入被刷入会话，您就可以在下一次请求重新填充表单时轻松检索它：

php

    return back()->withInput();

其他响应类型

response帮助程序可用于生成其他类型的响应实例。当不带参数调用response帮助程序时，将返回contracts的 Illuminate\Contracts\Routing\ResponseFactory 实现。此 Contract 提供了几种用于生成响应的有用方法。

视图响应

如果你需要控制响应的状态和标头，但还需要返回一个视图作为响应的内容，你应该使用 view 方法：

php

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

Of course, if you do not need to pass a custom HTTP status code or custom headers, you may use the global view helper function.

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 方法接受 filename 作为方法的第二个参数，这将确定下载文件的用户看到的文件名。最后，您可以将 HTTP 标头数组作为第三个参数传递给该方法：

php

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

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

WARNING

管理文件下载的 Symfony HttpFoundation 要求正在下载的文件具有 ASCII 文件名。

流式下载

有时，您可能希望将给定操作的字符串响应转换为可下载的响应，而不必将操作的内容写入磁盘。在这种情况下，您可以使用 streamDownload 方法。此方法接受 callback、filename 和可选的 headers 数组作为其参数：

php

    use App\Services\GitHub;

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

文件响应

file 方法可用于直接在用户的浏览器中显示文件，例如图像或 PDF，而不是启动下载。此方法接受文件的绝对路径作为其第一个参数，并接受标头数组作为其第二个参数：

php

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

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

响应宏

如果您想定义一个可以在各种路由和控制器中重复使用的自定义响应，您可以在 Response Facade 上使用 macro 方法。通常，您应该从应用程序的某个服务提供商（例如服务提供商） App\Providers\AppServiceProvider 的 boot 方法中调用此方法：

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 函数接受 name 作为其第一个参数，一个 closure 作为其第二个参数。从 ResponseFactory 实现或响应帮助程序调用宏名称时，将执行宏的闭包：

php

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

HTTP 响应 ​

创建响应 ​

字符串和数组 ​

响应对象 ​

Eloquent 模型和集合 ​

将标头附加到响应 ​

缓存控制中间件 ​

将 Cookie 附加到响应 ​

生成 Cookie 实例 ​

提前使 Cookie 过期 ​

Cookie 和加密 ​

重定向 ​

重定向到命名路由 ​

通过 Eloquent 模型填充参数 ​

重定向到 Controller 操作 ​

重定向到外部域 ​

使用闪存的会话数据重定向 ​

使用输入重定向 ​

其他响应类型 ​

视图响应 ​

JSON 响应 ​

文件下载 ​

流式下载 ​

文件响应 ​

响应宏 ​