HTTP 响应

• 创建响应
  • 添加响应头
  • 添加 Cookies
  • Cookies & 加密
• 重定向
  • 重定向到命名路由
  • 重定向到控制器操作
  • 重定向到外部域名
  • 重定向并闪存 Session 数据
• 其它响应类型
  • 视图响应
  • 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',
            ]);

添加 Cookies

响应实例的 cookie 方法可以让您轻松地为响应添加 Cookies。例如，可以使用 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 将多个 Cookies「排队」添加到应用的响应中。queue 方法接收一个要创建的 Cookie 实例。这些 Cookie 将会在发送到浏览器之前添加到响应：

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

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

Cookies & 加密

默认情况下，Laravel 生成的所有 Cookies 都会被加密并签名，以便客户端无法读取或修改它。如果要对应用生成的 Cookies 禁用加密，可以使用 App\Http\Middleware\EncryptCookies 中间件的 $except 属性，该文件位于 app/Http/Middleware 目录中：

/**
 * 不应被加密的 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 中间件组，或者应用了所有 Session 中间件：

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 模型填充参数

如果要重定向到用 Eloquent 模型来填充「ID」参数的路由，可以传递模型本身。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 方法来执行此操作，该方法会创建一个不会进行任何 URL 编码、验证或认证的 RedirectResponse：

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

重定向并闪存 Session 数据

重定向到一个新的 URL 和 闪存数据到 Session 经常是同时完成的。通常来说，在一个操作成功执行后会将成功信息闪存到 Session 中。为方便起见，可以使用流畅的链式方法来创建一个 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

其它响应类型

response 辅助函数可用于生成其它类型的响应。当不带参数调用 response 辅助函数时，会返回一个 Illuminate\Contracts\Routing\ResponseFactory Contract 的实现。该 Contract 提供了几种有用的方法来生成响应。

视图响应

如果需要控制响应的状态码和响应头，但同时需要返回一个 视图 作为响应内容，则应使用 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 方法中：

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