HTTP 响应

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

创建响应

字符串和数组

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

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

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

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

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

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

您知道您还可以从路由或控制器返回 Eloquent 集合吗？它们将自动转换为 JSON。不妨试一试！

响应对象

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

返回完整的 Response 实例允许您自定义响应的 HTTP 状态代码和标头。Response 实例继承自 Symfony\Component\HttpFoundation\Response 类，该类提供了各种用于构建 HTTP 响应的方法

1Route::get('/home', function () {
2    return response('Hello World', 200)
3        ->header('Content-Type', 'text/plain');
4});

Route::get('/home', function () {
    return response('Hello World', 200)
        ->header('Content-Type', 'text/plain');
});

Eloquent 模型和集合

您还可以直接从路由和控制器返回 Eloquent ORM 模型和集合。当您这样做时，Laravel 会自动将模型和集合转换为 JSON 响应，同时尊重模型的隐藏属性

1use App\Models\User;
2 
3Route::get('/user/{user}', function (User $user) {
4    return $user;
5});

use App\Models\User;

Route::get('/user/{user}', function (User $user) {
    return $user;
});

在响应中附加标头

请记住，大多数响应方法都是可链式的，从而可以流畅地构建响应实例。例如，您可以使用 header 方法在将一系列标头添加到响应中，然后再将其发送回用户

1return response($content)
2    ->header('Content-Type', $type)
3    ->header('X-Header-One', 'Header Value')
4    ->header('X-Header-Two', 'Header Value');

return response($content)
    ->header('Content-Type', $type)
    ->header('X-Header-One', 'Header Value')
    ->header('X-Header-Two', 'Header Value');

或者，您可以使用 withHeaders 方法来指定要添加到响应的标头数组

1return response($content)
2    ->withHeaders([
3        'Content-Type' => $type,
4        'X-Header-One' => 'Header Value',
5        'X-Header-Two' => 'Header Value',
6    ]);

return response($content)
    ->withHeaders([
        'Content-Type' => $type,
        'X-Header-One' => 'Header Value',
        'X-Header-Two' => 'Header Value',
    ]);

缓存控制中间件

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

1Route::middleware('cache.headers:public;max_age=2628000;etag')->group(function () {
2    Route::get('/privacy', function () {
3        // ...
4    });
5 
6    Route::get('/terms', function () {
7        // ...
8    });
9});

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 的名称、值和 cookie 应被视为有效的分钟数传递给此方法

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

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

cookie 方法还接受一些不太常用的参数。通常，这些参数具有与 PHP 原生 setcookie 方法的参数相同的目的和含义

1return response('Hello World')->cookie(
2    'name', 'value', $minutes, $path, $domain, $secure, $httpOnly
3);

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

如果您想确保 cookie 与传出的响应一起发送，但您尚未拥有该响应的实例，则可以使用 Cookie 外观模式来“排队” cookie，以便在发送响应时附加到响应。queue 方法接受创建 cookie 实例所需的参数。这些 cookie 将在传出的响应发送到浏览器之前附加到响应

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

use Illuminate\Support\Facades\Cookie;

Cookie::queue('name', 'value', $minutes);

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

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

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

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

提前使 Cookie 过期

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

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

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

如果您尚未拥有传出响应的实例，则可以使用 Cookie 外观模式的 expire 方法使 cookie 过期

1Cookie::expire('name');

Cookie::expire('name');

Cookie 和加密

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

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

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

重定向

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

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

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

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

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

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

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

重定向到命名路由

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

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

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

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

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

// For a route with the following URI: /profile/{id}

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

通过 Eloquent 模型填充参数

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

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

// For a route with the following URI: /profile/{id}

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

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

1/**
2 * Get the value of the model's route key.
3 */
4public function getRouteKey(): mixed
5{
6    return $this->slug;
7}

/**
 * Get the value of the model's route key.
 */
public function getRouteKey(): mixed
{
    return $this->slug;
}

重定向到控制器操作

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

1use App\Http\Controllers\UserController;
2 
3return redirect()->action([UserController::class, 'index']);

use App\Http\Controllers\UserController;

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

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

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

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

重定向到外部域名

有时您可能需要重定向到应用程序外部的域。您可以通过调用 away 方法来执行此操作，该方法创建一个 RedirectResponse，而没有任何额外的 URL 编码、验证或验证

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

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

使用闪存会话数据重定向

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

1Route::post('/user/profile', function () {
2    // ...
3 
4    return redirect('/dashboard')->with('status', 'Profile updated!');
5});

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

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

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

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

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

使用输入重定向

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

1return back()->withInput();

return back()->withInput();

其他响应类型

response 助手函数可用于生成其他类型的响应实例。当在没有参数的情况下调用 response 助手函数时，将返回 Illuminate\Contracts\Routing\ResponseFactory 契约的实现。此契约提供了几个用于生成响应的有用方法。

视图响应

如果您需要控制响应的状态和标头，但也需要返回视图作为响应的内容，则应使用 view 方法

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

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

当然，如果您不需要传递自定义 HTTP 状态代码或自定义标头，则可以使用全局 view 助手函数。

JSON 响应

json 方法会自动将 Content-Type 标头设置为 application/json，以及使用 json_encode PHP 函数将给定的数组转换为 JSON

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

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

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

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

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

文件下载

download 方法可用于生成强制用户浏览器下载给定路径的文件的响应。download 方法接受文件名作为该方法的第二个参数，这将确定下载文件的用户看到的文件名。最后，您可以将 HTTP 标头数组作为该方法的第三个参数传递

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

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

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

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

文件响应

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

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

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

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

流式响应

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

 1function streamedContent(): Generator {
 2    yield 'Hello, ';
 3    yield 'World!';
 4}
 5 
 6Route::get('/stream', function () {
 7    return response()->stream(function (): void {
 8        foreach (streamedContent() as $chunk) {
 9            echo $chunk;
10            ob_flush();
11            flush();
12            sleep(2); // Simulate delay between chunks...
13        }
14    }, 200, ['X-Accel-Buffering' => 'no']);
15});

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

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

use App\Models\User;

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

流式下载

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

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

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 服务提供者

 1<?php
 2 
 3namespace App\Providers;
 4 
 5use Illuminate\Support\Facades\Response;
 6use Illuminate\Support\ServiceProvider;
 7 
 8class AppServiceProvider extends ServiceProvider
 9{
10    /**
11     * Bootstrap any application services.
12     */
13    public function boot(): void
14    {
15        Response::macro('caps', function (string $value) {
16            return Response::make(strtoupper($value));
17        });
18    }
19}

<?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 助手函数调用宏名称时，将执行宏的闭包

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

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

序言

入门指南

架构概念

基础知识

深入探讨

安全

数据库

Eloquent ORM

测试

软件包

HTTP 响应

创建响应

字符串和数组

响应对象

Eloquent 模型和集合

在响应中附加标头

缓存控制中间件

在响应中附加 Cookie

提前使 Cookie 过期

Cookie 和加密

重定向

重定向到命名路由

通过 Eloquent 模型填充参数

重定向到控制器操作

重定向到外部域名

使用闪存会话数据重定向

使用输入重定向

其他响应类型

视图响应

JSON 响应

文件下载

文件响应

流式响应

流式 JSON 响应

流式下载

响应宏

产品

软件包

资源