HTTP 响应

• 创建响应
  • 为响应附加头信息
  • 为响应附加 Cookie
  • Cookie 与加密
• 重定向
  • 重定向到命名路由
  • 重定向到控制器动作
  • 重定向到外部域名
  • 重定向并闪存会话数据
• 其他响应类型
  • 视图响应
  • JSON 响应
  • 文件下载
  • 文件响应
• 响应宏

创建响应

字符串和数组

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

为响应附加头信息

请记住，大多数响应方法是可链式调用的，允许流畅地构建响应实例。例如，你可以使用 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 附加到响应。例如，你可以使用 cookie 方法生成一个 Cookie 并流畅地将其附加到响应实例，如下所示：

return response($content)
                ->header('Content-Type', $type)
                ->cookie('name', 'value', $minutes);

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

->cookie($name, $value, $minutes, $path, $domain, $secure, $httpOnly)

或者，你可以使用 Cookie facade 来“排队”要附加到应用程序的传出响应的 Cookie。queue 方法接受一个 Cookie 实例或创建 Cookie 实例所需的参数。这些 Cookie 将在响应发送到浏览器之前附加到传出响应：

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

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

Cookie 与加密

默认情况下，Laravel 生成的所有 Cookie 都是加密和签名的，以便客户端无法修改或读取它们。如果你想为应用程序生成的某些 Cookie 禁用加密，可以使用位于 app/Http/Middleware 目录中的 App\Http\Middleware\EncryptCookies 中间件的 $except 属性：

/**
 * 不应加密的 Cookie 名称。
 *
 * @var array
 */
protected $except = [
    'cookie_name',
];

重定向

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

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

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

Route::post('user/profile', function () {
    // 验证请求...

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

重定向到命名路由

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

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

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

// 对于具有以下 URI 的路由：profile/{id}

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

通过 Eloquent 模型填充参数

如果你要重定向到一个带有“ID”参数的路由，并且该参数是从 Eloquent 模型中填充的，可以直接传递模型。ID 将自动提取：

// 对于具有以下 URI 的路由：profile/{id}

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

如果你想自定义放置在路由参数中的值，应覆盖 Eloquent 模型上的 getRouteKey 方法：

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

重定向到控制器动作

你还可以生成到 控制器动作 的重定向。为此，将控制器和动作名称传递给 action 方法。请记住，你不需要指定控制器的完整命名空间，因为 Laravel 的 RouteServiceProvider 会自动设置基本控制器命名空间：

return redirect()->action('HomeController@index');

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

return redirect()->action(
    'UserController@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

其他响应类型

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，并使用 PHP 的 json_encode 函数将给定数组转换为 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);

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

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

流式下载

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

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

文件响应

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

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

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

响应宏

如果你想定义一个可以在多个路由和控制器中重用的自定义响应，可以在 Response facade 上使用 macro 方法。例如，从 服务提供者 的 boot 方法中：

<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Illuminate\Support\Facades\Response;

class ResponseMacroServiceProvider extends ServiceProvider
{
    /**
     * 注册应用程序的响应宏。
     *
     * @return void
     */
    public function boot()
    {
        Response::macro('caps', function ($value) {
            return Response::make(strtoupper($value));
        });
    }
}

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

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