HTTP 响应

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

创建响应

字符串和数组

所有路由和控制器都应该返回一个响应，以发送回用户的浏览器。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',
            ]);

缓存控制中间件

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

Route::middleware('cache.headers:public;max_age=2628000;etag')->group(function () {
    Route::get('/privacy', function () {
        // ...
    });
 
    Route::get('/terms', function () {
        // ...
    });
});

将 Cookie 附加到响应

你可以使用 cookie 方法将 Cookie 附加到传出的 Illuminate\Http\Response 实例。你应该将名称、值和 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 实例所需的 arguments。这些 Cookie 将在发送到浏览器之前附加到传出的响应中

use Illuminate\Support\Facades\Cookie;
 
Cookie::queue('name', 'value', $minutes);

如果你想生成一个 Symfony\Component\HttpFoundation\Cookie 实例，该实例可以在以后附加到响应实例，可以使用全局 cookie 助手。除非将此 Cookie 附加到响应实例，否则它不会发送回客户端

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

提前过期 Cookie

你可以通过传出响应的 withoutCookie 方法来过期 Cookie 以将其删除

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

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

Cookie::expire('name');

Cookie 和加密

默认情况下，由于 Illuminate\Cookie\Middleware\EncryptCookies 中间件，Laravel 生成的所有 Cookie 都会被加密并签名，以防止它们被客户端修改或读取。如果你想为应用程序生成的 Cookie 子集禁用加密，可以在应用程序的 bootstrap/app.php 文件中使用 encryptCookies 方法

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

重定向

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

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

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

Route::post('/user/profile', function () {
    // Validate the request...
 
    return back()->withInput();
});

重定向到命名路由

当你调用没有参数的 redirect 助手时，将返回一个 Illuminate\Routing\Redirector 实例，允许你调用 Redirector 实例上的任何方法。例如，要生成到命名路由的 RedirectResponse，可以使用 route 方法

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

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

// For a route with the following URI: /profile/{id}
 
return redirect()->route('profile', ['id' => 1]);

通过 Eloquent 模型填充参数

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

// For a route with the following URI: /profile/{id}
 
return redirect()->route('profile', [$user]);

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

/**
 * Get the value of the model's route key.
 */
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`，并使用 `json_encode` PHP 函数将给定的数组转换为 JSON。

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

如果您想创建 JSONP 响应，则可以将 `json` 方法与 `withCallback` 方法结合使用。

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

文件下载

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

流式响应

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

function streamedContent(): Generator {
    yield 'Hello, ';
    yield 'World!';
}
 
Route::get('/stream', function () {
    return response()->stream(function (): void {
        foreach (streamedContent() as $chunk) {
            echo $chunk;
            ob_flush();
            flush();
            sleep(2); // Simulate delay between chunks...
        }
    }, 200, ['X-Accel-Buffering' => 'no']);
});

在内部，Laravel 使用 PHP 的输出缓冲功能。如您在上面的示例中看到的，您应该使用 `ob_flush` 和 `flush` 函数将缓冲的内容推送到客户端。

流式传输的 JSON 响应

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

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

流式传输的下载

有时，您可能希望将给定操作的字符串响应转换为可下载的响应，而无需将操作的内容写入磁盘。您可以在这种情况下使用 `streamDownload` 方法。此方法接受一个回调函数、文件名和一个可选的标头数组作为其参数。

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

响应宏

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

<?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` 帮助程序中调用宏名称时，将执行宏的闭包。

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