响应 · laravel 5.4

<article><h1>Laravel 的请求返回 Response</h1><ul><li><a href="#creating-responses">创建响应</a><ul><li><a href="#attaching-headers-to-responses">附加头信息至响应</a></li><li><a href="#attaching-cookies-to-responses">附加 Cookie 至响应</a></li><li><a href="#cookies-and-encryption">Cookies 加密</a></li></ul></li><li><a href="#redirects">重定向</a><ul><li><a href="#redirecting-named-routes">重定向至命名路由</a></li><li><a href="#redirecting-controller-actions">重定向至控制器行为</a></li><li><a href="#redirecting-with-flashed-session-data">重定向并附加 Session 闪存数据</a></li></ul></li><li><a href="#other-response-types">其他响应类型</a><ul><li><a href="#view-responses">视图响应</a></li><li><a href="#json-responses">JSON 响应</a></li><li><a href="#file-downloads">文件下载</a></li><li><a href="#file-responses">文件响应</a></li></ul></li><li><a href="#response-macros">响应宏</a></li></ul><a name="creating-responses"></a><h2><a href="#creating-responses">创建响应</a></h2><h4>字符串 & 数组</h4>所有路由和控制器都会返回一个响应并返回给用户的浏览器。Laravel 提供了几种不同的方式来返回响应。最基本的响应就是从路由或控制器返回一串字符串。框架会自动将字符串转换为一个完整的 HTTP 响应：<pre class=" language-php"><code class=" language-php">Route::get('/', function () { return 'Hello World'; });</code></pre>从路由和控制器不仅能返回字符串，也可以返回数组。框架也会自动地将数组转为 JSON 响应：<pre class=" language-php"><code class=" language-php">Route::get('/', function () { return [1, 2, 3]; });</code></pre><blockquote class="has-icon tip"><div class="flag"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:a="http://ns.adobe.com/AdobeSVGViewerExtensions/3.0/" version="1.1" x="0px" y="0px" width="56.6px" height="87.5px" viewBox="0 0 56.6 87.5" enable-background="new 0 0 56.6 87.5" xml:space="preserve"><path fill="#FFFFFF" d="M28.7 64.5c-1.4 0-2.5-1.1-2.5-2.5v-5.7 -5V41c0-1.4 1.1-2.5 2.5-2.5s2.5 1.1 2.5 2.5v10.1 5 5.8C31.2 63.4 30.1 64.5 28.7 64.5zM26.4 0.1C11.9 1 0.3 13.1 0 27.7c-0.1 7.9 3 15.2 8.2 20.4 0.5 0.5 0.8 1 1 1.7l3.1 13.1c0.3 1.1 1.3 1.9 2.4 1.9 0.3 0 0.7-0.1 1.1-0.2 1.1-0.5 1.6-1.8 1.4-3l-2-8.4 -0.4-1.8c-0.7-2.9-2-5.7-4-8 -1-1.2-2-2.5-2.7-3.9C5.8 35.3 4.7 30.3 5.4 25 6.7 14.5 15.2 6.3 25.6 5.1c13.9-1.5 25.8 9.4 25.8 23 0 4.1-1.1 7.9-2.9 11.2 -0.8 1.4-1.7 2.7-2.7 3.9 -2 2.3-3.3 5-4 8L41.4 53l-2 8.4c-0.3 1.2 0.3 2.5 1.4 3 0.3 0.2 0.7 0.2 1.1 0.2 1.1 0 2.2-0.8 2.4-1.9l3.1-13.1c0.2-0.6 0.5-1.2 1-1.7 5-5.1 8.2-12.1 8.2-19.8C56.4 12 42.8-1 26.4 0.1zM43.7 69.6c0 0.5-0.1 0.9-0.3 1.3 -0.4 0.8-0.7 1.6-0.9 2.5 -0.7 3-2 8.6-2 8.6 -1.3 3.2-4.4 5.5-7.9 5.5h-4.1H28h-0.5 -3.6c-3.5 0-6.7-2.4-7.9-5.7l-0.1-0.4 -1.8-7.8c-0.4-1.1-0.8-2.1-1.2-3.1 -0.1-0.3-0.2-0.5-0.2-0.9 0.1-1.3 1.3-2.1 2.6-2.1H41C42.4 67.5 43.6 68.2 43.7 69.6zM37.7 72.5H26.9c-4.2 0-7.2 3.9-6.3 7.9 0.6 1.3 1.8 2.1 3.2 2.1h4.1 0.5 0.5 3.6c1.4 0 2.7-0.8 3.2-2.1L37.7 72.5z"></path></svg></div> 你知道吗？ <a href="/docs/5.4/eloquent-collections">Eloquent 集合</a> 也可以从路由和控制器中直接返回，它们会自动转为 JSON 响应。试试吧！</blockquote><h4>响应对象</h4>一般来说，你不需要从路由方法返回简单的字符串或数组。而是需要返回整个 <code class=" language-php">Illuminate\Http\Response</code> 实例或 <a href="/docs/5.4/views">视图</a>。当返回整个 <code class=" language-php">Response</code> 实例时，Laravel 允许自定义响应的 HTTP 状态码和响应头信息。<code class=" language-php">Response</code> 实例继承自 <code class=" language-php">Symfony\Component\HttpFoundation\Response</code> 类，该类提供了丰富的构建 HTTP 响应的方法：<pre class=" language-php"><code class=" language-php">Route::get('home', function () { return response('Hello World', 200) ->header('Content-Type', 'text/plain'); });</code></pre><a name="attaching-headers-to-responses"></a><h4>附加头信息至响应</h4>大部分的响应方法都是可链式调用的，以使你更酣畅淋漓的创建响应实例。例如，你可以在响应返回给用户前使用 <code class=" language-php">header</code> 方法向响应实例中附加一系列的头信息：<pre class=" language-php"><code class=" language-php">return response($content) ->header('Content-Type', $type) ->header('X-Header-One', 'Header Value') ->header('X-Header-Two', 'Header Value');</code></pre>或者，你可以使用 <code class=" language-php">withHeaders</code> 方法来指定一个包含头信息的数组：<pre class=" language-php"><code class=" language-php">return response($content) ->withHeaders([ 'Content-Type' => $type, 'X-Header-One' => 'Header Value', 'X-Header-Two' => 'Header Value', ]);</code></pre><a name="attaching-cookies-to-responses"></a><h4>附加 Cookie 至响应</h4>通过响应对象的 cookie 方法可以让你轻松的附加 cookies 至响应。你可以使用 <code class=" language-php">cookie</code> 方法来生成 cookie 并附加至响应实例，像这样：<pre class=" language-php"><code class=" language-php">return response($content) ->header('Content-Type', $type) ->cookie('name', 'value', $minutes);</code></pre><code class=" language-php">cookie</code> 方法也接受另外几个参数，它们的使用频率较低。通常，这些参数和给予原生 PHP 的 <a href="https://secure.php.net/manual/en/function.setcookie.php">setcookie</a> 方法的参数有着相同的目的和含义：<pre class=" language-php"><code class=" language-php">->cookie($name, $value, $minutes, $path, $domain, $secure, $httpOnly)</code></pre><a name="cookies-and-encryption"></a><h4>Cookies 加密</h4>默认情况下，Laravel 生成的所有 cookie 都是加密并通过签名验证的，因此他们并不能够在客户端被修改和读取。如果你想对你的应用程序生成的部分 cookie 禁用加密，可以使用 <code class=" language-php">App\Http\Middleware\EncryptCookies</code> 中间件的 <code class=" language-php">$except</code> 属性，该文件存储在 <code class=" language-php">app/Http/Middleware</code>：<pre class=" language-php"><code class=" language-php">/** * 无需被加密的 cookie 名 * * @var array */ protected $except = [ 'cookie_name', ];</code></pre><a name="redirects"></a><h2><a href="#redirects">重定向</a></h2>重定向响应是 <code class=" language-php">Illuminate\Http\RedirectResponse</code> 类的实例，并且包含用户需要重定向至另一个 URL 所需的头信息。Laravel 提供了许多方法用于生成 <code class=" language-php">RedirectResponse</code> 实例。最简单的方法是使用全局的 <code class=" language-php">redirect</code> 辅助函数：<pre class=" language-php"><code class=" language-php">Route::get('dashboard', function () { return redirect('home/dashboard'); });</code></pre>有些情况下你可能希望用户重定向至上级一页面，比如，当提交表单失败时。这时可以使用全局辅助函数 <code class=" language-php">back</code>。由于此功能利用了 <a href="/docs/5.4/session">Session</a>，请确保调用 <code class=" language-php">back</code> 函数的路由是使用 <code class=" language-php">web</code> 中间件组或应用了所有的 Session 中间件：<pre class=" language-php"><code class=" language-php">Route::post('user/profile', function () { // 验证请求... return back()->withInput(); });</code></pre><a name="redirecting-named-routes"></a><h3>重定向至命名路由</h3>当调用不带参数的辅助函数 <code class=" language-php">redirect</code> 时，会返回一个 <code class=" language-php">Illuminate\Routing\Redirector</code> 实例，该实例允许你调用 <code class=" language-php">Redirector</code> 实例的任何方法。例如，生成一个 <code class=" language-php">RedirectResponse</code> 重定向至一个被命名的路由时，您可以使用 <code class=" language-php">route</code> 方法：<pre class=" language-php"><code class=" language-php">return redirect()->route('login');</code></pre>如果你的路由有参数，它们可以作为 <code class=" language-php">route</code> 方法的第二个参数来传递：<pre class=" language-php"><code class=" language-php">// 对于该 URI 的路由: profile/{id} return redirect()->route('profile', ['id' => 1]);</code></pre><h4>通过 Eloquent 模型填充参数</h4>如果要重定向到一个使用了 Eloquent 模型并需要传递 ID 参数的路由上，你只需传递模型本身即可，ID 会自动提取。<pre class=" language-php"><code class=" language-php">// 对于此路由: profile/{id} return redirect()->route('profile', [$user]);</code></pre>如果想要更改自动提取的路由参数的键值，你应该重写 Eloquent 模型里的 <code class=" language-php">getRouteKey</code> 方法：<pre class=" language-php"><code class=" language-php">/** * 获取模型的路由键值. * * @return mixed */ public function getRouteKey() { return $this->slug; }</code></pre><a name="redirecting-controller-actions"></a><h3>重定向至控制器行为</h3>你可能也会用到生成重定向至 <a href="/docs/5.4/controllers">控制器行为</a>的响应。要实现此功能，可以向 <code class=" language-php">action</code> 方法传递控制器和行为名称作为参数来实现。请记住，这里并不需要指定完整的命名空间，因为 Laravel 的 <code class=" language-php">RouteServiceProvider</code> 会自动设置基本的控制器命名空间：<pre class=" language-php"><code class=" language-php">return redirect()->action('HomeController@index');</code></pre>如果控制器路由包含参数则需要把他们作为 <code class=" language-php">action</code> 函数的第二个参数传递：<pre class=" language-php"><code class=" language-php">return redirect()->action( 'UserController@profile', ['id' => 1] );</code></pre><a name="redirecting-with-flashed-session-data"></a><h3>重定向并附加 Session 闪存数据</h3>重定向至一个新的 URL 的同时通常会 <a href="/docs/5.4/session#flash-data">附加 Session 闪存数据</a>。一般来说，在控制器行为成功地执行之后才会向 Session 中闪存成功的消息。为了方便，你可以利用链式调用的方式创建一个 RedirectResponse 的实例并闪存数据至 Session：<pre class=" language-php"><code class=" language-php">Route::post('user/profile', function () { // 更新用户的信息 return redirect('dashboard')->with('status', 'Profile updated!'); });</code></pre>用户重定向至指定页面后，你可以从 Session 中获取并展示闪存数据。例如，使用 <a href="/docs/5.4/blade">Blade 语法</a>：<pre class=" language-php"><code class=" language-php">@if (session('status')) <div class="alert alert-success"> {{ session('status') }} </div> @endif</code></pre><a name="other-response-types"></a><h2><a href="#other-response-types">其他响应类型</a></h2>使用全局辅助函数 <code class=" language-php">response</code> 可以轻松的生成其他类型的响应实例。当不带任何参数调用 <code class=" language-php">response</code> 时，将会返回 Illuminate\Contracts\Routing\ResponseFactory <a href="/docs/5.4/contracts">Contract</a> 的实现。Contract 包含许多有用的用来辅助生成响应的方法。<a name="view-responses"></a><h3>视图响应</h3>如果你的响应内容不但需要控制响应状态码和响应头信息而且还需要返回一个 <a href="/docs/5.4/views">视图</a>，这时你应该使用 <code class=" language-php">view</code> 方法：<pre class=" language-php"><code class=" language-php">return response() ->view('hello', $data, 200) ->header('Content-Type', $type);</code></pre>当然，如果不需要自定义 HTTP 状态码和响应头信息，则可使用全局的 <code class=" language-php">view</code> 辅助函数。<a name="json-responses"></a><h3>JSON 响应</h3><code class=" language-php">json</code> 方法会自动将 <code class=" language-php">Content-Type</code> 响应头信息设置为 <code class=" language-php">application/json</code>，并使用 PHP 的 <code class=" language-php">json_encode</code> 函数将数组转换为 JSON 字符串。<pre class=" language-php"><code class=" language-php">return response()->json([ 'name' => 'Abigail', 'state' => 'CA' ]);</code></pre>如果想要创建一个 JSONP 响应，则可以使用 <code class=" language-php">json</code> 方法并结合 withCallback 函数：<pre class=" language-php"><code class=" language-php">return response() ->json(['name' => 'Abigail', 'state' => 'CA']) ->withCallback($request->input('callback'));</code></pre><a name="file-downloads"></a><h3>文件下载</h3><code class=" language-php">download</code> 方法可以用于生成强制让用户的浏览器下载指定路径文件的响应。<code class=" language-php">download</code> 方法接受文件名称作为方法的第二个参数，此名称为用户下载文件时看见的文件名称。最后，你可以传递一个包含 HTTP 头信息的数组作为第三个参数传入该方法：<pre class=" language-php"><code class=" language-php">return response()->download($pathToFile); return response()->download($pathToFile, $name, $headers);</code></pre><blockquote class="has-icon note"><div class="flag"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:a="http://ns.adobe.com/AdobeSVGViewerExtensions/3.0/" version="1.1" x="0px" y="0px" width="90px" height="90px" viewBox="0 0 90 90" enable-background="new 0 0 90 90" xml:space="preserve"><path fill="#FFFFFF" d="M45 0C20.1 0 0 20.1 0 45s20.1 45 45 45 45-20.1 45-45S69.9 0 45 0zM45 74.5c-3.6 0-6.5-2.9-6.5-6.5s2.9-6.5 6.5-6.5 6.5 2.9 6.5 6.5S48.6 74.5 45 74.5zM52.1 23.9l-2.5 29.6c0 2.5-2.1 4.6-4.6 4.6 -2.5 0-4.6-2.1-4.6-4.6l-2.5-29.6c-0.1-0.4-0.1-0.7-0.1-1.1 0-4 3.2-7.2 7.2-7.2 4 0 7.2 3.2 7.2 7.2C52.2 23.1 52.2 23.5 52.1 23.9z"></path></svg></div> 管理文件下载的扩展包 Symfony HttpFoundation，要求下载文件名必须是 ASCII 编码。</blockquote><a name="file-responses"></a><h3>文件响应</h3><code class=" language-php">file</code> 方法可以用来显示一个文件，例如图片或者 PDF，直接在用户的浏览器中显示，而不是开始下载。这个方法的第一个参数是文件的路径，第二个参数是包含头信息的数组：<pre class=" language-php"><code class=" language-php">return response()->file($pathToFile); return response()->file($pathToFile, $headers);</code></pre><a name="response-macros"></a><h2><a href="#response-macros">响应宏</a></h2>如果你想要自定义可以在很多路由和控制器重复使用的响应，可以使用 <code class=" language-php">Response</code> Facade 实现的 <code class=" language-php">macro</code> 方法。举个例子，来自 <a href="/docs/5.4/providers">服务提供者</a>的 <code class=" language-php">boot</code> 方法：<pre class=" language-php"><code class=" language-php"><?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)); }); } }</code></pre><code class=" language-php">macro</code> 函数第一个参数为宏名称，第二个参数为闭包函数。宏的闭包函数会在 <code class=" language-php">ResponseFactory</code> 的实现或者辅助函数 <code class=" language-php">response</code> 调用宏名称的时候运行：<pre class=" language-php"><code class=" language-php">return response()->caps('foo');</code></pre><h2>译者署名</h2><table><thead><tr><th>用户名</th><th>头像</th><th>职能</th><th>签名</th></tr></thead><tbody><tr><td><a href="http://weibo.com/wangkaibo">@王凯波</a></td><td><img class="avatar-66 rm-style" src="https://dn-phphub.qbox.me/uploads/avatars/1924_1487053084.jpeg?imageView2/1/w/100/h/100"></td><td>翻译</td><td>面向工资编程 😆 <a href="https://github.com/wangkaibo/">@wangkaibo</a></td></tr></tbody></table></article>