响应 laravel laravelphp 中文文档

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

创建响应

字符串 & 数组
所有路由和控制器处理完业务逻辑之后都会返回响应到用户的浏览器，Laravel 提供了多种不同的响应方式，其中最基本就是从路由或控制器返回一个简单的字符串，框架会自动将这个字符串转化为一个完整的 HTTP 响应：

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

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

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

技巧
你知道从路由或控制器还可以返回 Eloquent 集合吗？他们也会自动转化为 JSON 响应！试试看吧!

Response 对象
通常情况下会只返回简单的字符串或数组，大多数时候，需要返回一个完整的 php Illuminate\Http\Response 实例或视图.

返回一个完整的 php Response 实例允许你自定义返回的 HTTP 状态码和HTTP返回头信息。 php Response 实例继承自 php 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;
});

请记住，大多数响应方法都是可以链式调用的，它允许你流畅地构建响应实例. 例如, 例如，在将响应发送回用户之前，可以使用 php header 方法添加一系列的返回Header到响应实例中：

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

或者，你也可以使用 php withHeaders 方法指定一个标头数组添加到响应中：

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

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

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

你可以使用 php cookie 方法将 cookie 附加到传出的 php illumize\Http\Response 实例。你应将 cookie 的名称、值和有效分钟数传递给此方法：

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

php cookie 方法还接受一些使用频率较低的参数。通常，这些参数的目的和意义与 PHP 的原生 setcookie 的参数相同：

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

如果你希望确保 cookie 与传出响应一起发送，但你还没有该响应的实例，则可以使用 php Cookie facade 将 cookie 加入队列，以便在发送响应时附加到响应中。php queue 方法接受创建 cookie 实例所需的参数。在发送到浏览器之前，这些 cookies 将附加到传出的响应中：

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

生成 Cookie 实例
如果要生成一个 php Symfony\Component\HttpFoundation\Cookie 实例，打算稍后附加到响应实例中，你可以使用全局 php cookie 助手函数。此 cookie 将不会发送回客户端，除非它被附加到响应实例中：

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

提前过期 Cookie
你可以通过响应中的 php withoutCookie 方法使 cookie 过期，用于删除 cookie ：

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

如果尚未有创建响应的实例，则可以使用 php Cookie facade 中的 php expire 方法使 Cookie 过期：

Cookie::expire('name');

Cookies 和加密

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

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

重定向

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

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

有时你可能希望将用户重定向回他们之前的页面，例如当提交的表单无效时。你可以通过使用全局的 php back 辅助函数来实现这一点。由于这个功能利用了session，请确保调用 php back 函数的路由使用了 php web 中间件组：

Route::post('/user/profile', function () {
    // 验证请求参数
    return back()->withInput();
});

重定向到命名路由

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

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

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

// 对于具有以下URI的路由: /profile/{id}
return redirect()->route('profile', ['id' => 1]);

通过 Eloquent 模型填充参数
如果你正在重定向到一个带有「ID」参数的路由，并且这个参数是从 Eloquent 模型中获取的，你可以直接传递这个模型本身。ID 将会自动被提取出来：

// 对于具有以下URI的路由:  /profile/{id}
return redirect()->route('profile', [$user]);

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

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

重定向到控制器操作

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

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

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

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

重定向到外部域名

有时你可能需要重定向到应用程序之外的域名。你可以通过调用 php away 方法，它会创建一个不带有任何额外的 URL 编码、有效性校验和检查 php RedirectResponse 实例：

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

重定向并使用闪存的 Session 数据

重定向到新的 URL 和向 session 闪存数据通常同时进行。通常，在成功执行某个操作后，比如在 session 中闪存一个成功消息时，会这样做。为了方便起见，你可以创建一个 php RedirectResponse 实例，并在单一的流畅方法链中向 session 闪存数据：

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

在用户被重定向之后，你可以从 session 中显示闪存的消息。例如，使用 Blade 模板语法：

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

输入重定向
在将用户重定向到新位置之前，你可以使用 php RedirectResponse 实例提供的 php withInput 方法，将当前请求的输入数据闪存到 session 中。这通常在用户遇到验证错误时进行。一旦输入数据被闪存到 session 中，你可以在下一个请求中轻松检索它，以便重新填充表单。

return back()->withInput();

其他响应类型

php response 助手可用于生成其他类型的响应实例。在 php response 助手被无参数调用时, 回返回一个 php Illuminate\Contracts\Routing\ResponseFactory 契约的实现。此契约提供了几个有效的生成响应。

响应视图

若你需要控制响应状态和标头并且返回一个视图响应内容, 你应该使用 php view 方法:

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

当然, 假设你不需要传递自定义 HTTP 状态代码或自定义标头, 则可以使用全局 php view 辅助函数。

JSON 响应

php json 方法会自动将设置 php Content-Type 标头设置为 php application/json, 同时会使用 PHP 函数 php json_encode 把给定的数组转换为 JSON:

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

如果你更愿意创建一个 JSONP 响应, 你可以把 php json 方法和 php withCallback 方法一起使用:

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

文件下载

php download 方法可以用来生成一个响应，该响应会强制用户浏览器下载指定路径的文件。 php download 方法接受一个文件名作为方法的第二个参数，这将决定用户在下载文件时看到的文件名。最后，你可以将一组 HTTP 标头作为该方法的第三个参数传递：

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

[!警告]
Symfony HttpFoundation,下载的文件必须有一个 ASCII 码的文件名。

流式下载
有时你可能希望将给定操作的字符串响应转换为可下载的响应，而不必将操作的内容写入磁盘。在这种情况下，你可以使用 php streamDownload 方法。此方法接受一个回调函数、文件名以及一个可选的头部数组作为参数：

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

文件响应

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

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

响应宏

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

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

php macro 函数接受一个名称作为其第一个参数和一个闭包作为其第二个参数。当从 php ResponseFactory 实现或 php response 辅助函数调用宏名称时，将执行宏的闭包：

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