六、基础组件 —— HTTP 响应

创建响应

字符串 & 数组

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

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

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

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

注：你知道还可以从路由或控制器返回 Eloquent 集合吗？他们也会被自动转化为 JSON 响应。

Response 对象

通常，我们并不只是从路由动作简单返回字符串和数组，大多数情况下，都会返回一个完整的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，Laravel 会自动将 ETag 标识符设置为响应内容的 MD5 哈希值：

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

    Route::get('terms', function () {
        // ...
    });
});

添加 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 「队列」， Cookie 以附加到应用程序的传出响应。 queue 方法接受一个 Cookie 实例或创建 Cookie 实例所需的参数。这些 cookie 在发送到浏览器之前会附加到传出响应中：

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

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

Cookies & 加密

默认情况下，Laravel 生成的所有 Cookie 都是经过加密和签名，因此不能被客户端修改或读取。如果你想要应用程序生成的部分 Cookie 不被加密，那么可以使用在 app/Http/Middleware 目录中 App\Http\Middleware\EncryptCookies 中间件的 $except 属性：

/**
 * 不需要被加密的cookies名称
 *
 * @var array
 */
protected $except = [
    'cookie_name',
];

重定向

重定向响应是 Illuminate\Http\RedirectResponse 类的实例，并且包含用户需要重定向至另一个 URL 所需的头信息。Laravel 提供了几种方法用于生成 RedirectResponse 实例。其中最简单的方法是使用全局辅助函数 redirect：

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

有时候你可能希望将用户重定向到之前的位置，比如提交的表单无效时。这时你可以使用全局辅助函数 back 来执行此操作。由于这个功能利用了会话控制，请确保调用 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]);

如果你想要自定义这个路由参数中的默认参数名，需要重写模型实例上的 getRouteKey 方法：

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

跳转到控制器 Action

还可以生成到 controller action 的跳转。要达到这个目的，只要把控制器和 action 的名称传递给 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 () {
    // Update the user's profile...
    return redirect('dashboard')->with('status', 'Profile updated!');
});

在用户跳转后，可以显示 session 中的传送数据。比如使用 Blade syntax：

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

其它的响应类型

response 助手可以用于生成其它类型的响应实例。当还带参数调用 response 助手时，返回 Illuminate\Contracts\Routing\ResponseFactory 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 响应，可以结合 withCallback 方法使用 json 方法：

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

或者直接使用 jsonp 方法：

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

文件下载

download 方法可以用于生成强制用户浏览器下载给定路径文件的响应。 download 方法文件名作为其第二个参数，它将作为用户下载文件的文件名。最后，你可以传递 HTTP 头信息数组作为其第三个参数：

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

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

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

注: 用于管理文件下载的 Symfony HttpFoundation 要求下载的文件有一个 ASCII 文件名。

举个例子，我们可以通过以下代码下载图片：

Route::get('download/response', function() {
    return response()->download(storage_path('app/photo/test.jpg'), '测试图片.jpg');
});

流下载

有时，你可能希望将给定操作的字符串响应转换为下载响应，而不需要将其写入磁盘。此时可以使用 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 门面上的 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');

在浏览器中访问 /macro/response，输出入下：

foo