響應 · laravel 5.3 中文文檔

# HTTP 響應 - [創建響應](#creating-responses) - [附加標頭至響應](#attaching-headers-to-responses) - [附加 Cookies 至響應](#attaching-cookies-to-responses) - [加密 Cookie](#cookies-and-encryption) - [重定向](#redirects) - [重定向至命名路由](#redirecting-named-routes) - [重定向至控制器行為](#redirecting-controller-actions) - [重定向并加上 Session 閃存數據](#redirecting-with-flashed-session-data) - [其它響應類型](#other-response-types) - [視圖響應](#view-responses) - [JSON 響應](#json-responses) - [文件下載](#file-downloads) - [文件響應](#file-responses) - [響應宏](#response-macros) <a name="creating-responses"></a> ## 創建響應 #### 字符串 & 數組所有的路由及控制器必須返回某個類型的響應，并發送回用戶的瀏覽器。Laravel 提供了幾種不同的方法來返回響應。最基本的響應就是從路由或控制器簡單的返回一個字符串。指定的字符串會被框架自動轉換成 HTTP 響應： Route::get('/', function () { return 'Hello World'; }); 從路由和控制器不僅可以返回字符串，也可以直接返回數組，這個數組將會被自動轉換為 JSON 響應： Route::get('/', function () { return [1, 2, 3]; }); > {tip} 在路由或控制器中也可以返回 [Eloquent 集合](/docs/{{version}}/eloquent-collections)，集合將被自動轉換為 JSON 數據，試一下吧。 #### 響應對象通常情況下，不需要從路由方法返回字符串或數組，需要的是返回完整的 `Illuminate\Http\Response` 實例或是一個 [視圖](/docs/{{version}}/views)。返回一個完整的 `Response` 實例時，就能夠自定義響應的 HTTP 狀態碼以及標頭。`Response` 實例繼承了 `Symfony\Component\HttpFoundation\Response` 類，其提供了很多創建 HTTP 響應的方法： Route::get('home', function () { return response('Hello World', 200) ->header('Content-Type', 'text/plain'); }); > **注意：**有關 `Response` 方法的完整列表可以參照 [API 文檔](http://laravel-china.org/api/master/Illuminate/Http/Response.html) 以及 [Symfony API 文檔](http://api.symfony.com/2.7/Symfony/Component/HttpFoundation/Response.html)。 <a name="attaching-headers-to-responses"></a> #### 附加標頭至響應大部份的響應方法是可鏈式調用的，這讓你可以順暢的創建響應。舉例來說，你可以在響應發送給用戶之前，使用 `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', ]); <a name="attaching-cookies-to-responses"></a> #### 附加 Cookies 至響應通過響應實例的 `cookie` 輔助方法可以讓你輕松的附加 cookies 至響應。舉個例子，你可以使用 `cookie` 方法來生成 cookie 并附加至響應實例： return response($content) ->header('Content-Type', $type) ->cookie('name', 'value', $minutes); `cookie` 方法可以接受額外的可選參數，傳遞給 PHP 原生 [設置 cookie](http://php.net/manual/en/function.setcookie.php) 方法： ->cookie($name, $value, $minutes, $path, $domain, $secure, $httpOnly) <a name="cookies-and-encryption"></a> #### Cookie 與加密默認情況下，所有 Laravel 生成的 cookies 都會被加密并加上認證標識，因此無法被用戶讀取及修改。如果你想停止對某個 cookies 的加密，則可以利用 `App\Http\Middleware\EncryptCookies` 中間件的 `$except` 屬性： /** * 無需被加密的 cookies 名稱。 * * @var array */ protected $except = [ 'cookie_name', ]; <a name="redirects"></a> ## 重定向重定向響應是類 `Illuminate\Http\RedirectResponse` 的實例，并且包含用戶要重定向至另一個 URL 所需的標頭。有幾種方法可以生成 `RedirectResponse` 的實例。最簡單的方式就是通過全局的 `redirect` 輔助函數： Route::get('dashboard', function () { return redirect('home/dashboard'); }); 有時你可能希望將用戶重定向至前一個位置，例如當提交一個無效的表單之后。這時可以使用全局的 `back` 輔助函數來達成這個目的。保證路由調用的 `back` 函數使用了 `web` 中間件組或在所有的 session 中間件添加： Route::post('user/profile', function () { // 驗證請求。。。 return back()->withInput(); }); <a name="redirecting-named-routes"></a> ### 重定向至命名路由當你調用 `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; } <a name="redirecting-controller-actions"></a> ### 重定向至控制器行為你可能也會希望生成重定向至 [控制器的行為](/docs/{{version}}/controllers)。要做到這一點，只需傳遞控制器及行為名稱至 `action` 方法。請記得，你不需要指定完整的命名空間，因為 Laravel 的 `RouteServiceProvider` 會自動設置默認的控制器命名空間： return redirect()->action('HomeController@index'); 當然，如果你的控制器路由需要參數的話，你可以傳遞它們至 `action` 方法的第二個參數： return redirect()->action( 'UserController@profile', ['id' => 1] ); <a name="redirecting-with-flashed-session-data"></a> ### 重定向并加上 Session 閃存數據通常重定向至新的 URL 時會一并 [寫入閃存數據至 session](/docs/{{version}}/session#flash-data)。所以為了方便，你可以利用鏈式調用的方式創建一個 `RedirectResponse` 的實例 **并** 閃存數據至 Session。這對于在一個動作之后保存狀態消息相當方便： Route::post('user/profile', function () { // 更新用戶的配置文件。。。 return redirect('dashboard')->with('status', 'Profile updated!'); }); 當然，在用戶重定向至新的頁面后，你可以獲取并顯示 [session](/docs/{{version}}/session) 的閃存數據。舉個例子，使用 [Blade 的語法](/docs/{{version}}/blade)： @if (session('status')) <div class="alert alert-success"> {{ session('status') }} </div> @endif <a name="other-response-types"></a> ## 其它響應類型使用輔助函數 `response` 可以輕松的生成其它類型的響應實例。當你調用輔助函數 `response` 且不帶任何參數時，將會返回 `Illuminate\Contracts\Routing\ResponseFactory` [contract](/docs/{{version}}/contracts) 的實現。此 Contract 提供了一些有用的方法來生成響應。 <a name="view-responses"></a> ### 視圖響應如果你想要控制響應狀態碼及標頭，同時也想要返回一個 [視圖](/docs/{{version}}/views) 作為返回的內容時，則可以使用 `view` 方法： return response() ->view('hello', $data, 200) ->header('Content-Type', $type); 當然，如果你沒有自定義 HTTP 狀態碼及標頭的需求，則可以簡單的使用全局的 `view` 輔助函數。 <a name="json-responses"></a> ### JSON 響應 `json` 方法會自動將標頭的 `Content-Type` 設置為 `application/json`，并通過 PHP 的 `json_encode` 函數將指定的數組轉換為 JSON： return response()->json([ 'name' => 'Abigail', 'state' => 'CA' ]); 如果你想創建一個 JSONP 響應，則可以使用 `json` 方法并加上 `setCallback`： return response() ->json(['name' => 'Abigail', 'state' => 'CA']) ->withCallback($request->input('callback')); <a name="file-downloads"></a> ### 文件下載 `download` 方法可以用于生成強制讓用戶的瀏覽器下載指定路徑文件的響應。`download` 方法接受文件名稱作為方法的第二個參數，此名稱為用戶下載文件時看見的文件名稱。最后，你可以傳遞一個 HTTP 標頭的數組作為第三個參數傳入該方法： return response()->download($pathToFile); return response()->download($pathToFile, $name, $headers); > **注意：**管理文件下載的擴展包 Symfony HttpFoundation，要求下載文件必須是 ASCII 文件名。 <a name="file-responses"></a> ### 文件響應 `file` 方法可以被用來顯示一個文件，例如圖片或者 PDF，直接在用戶的瀏覽器中顯示，而不是下載。這個方法的第一個參數是文件的路徑，第二個參數是表頭數組： return response()->file($pathToFile); return response()->file($pathToFile, $headers); <a name="response-macros"></a> ## 響應宏如果你想要自定義可以在很多路由和控制器重復使用的響應，可以使用 `Illuminate\Contracts\Routing\ResponseFactory` 實現的方法 `macro`。舉個例子，來自 [服務提供者的](/docs/{{version}}/providers) `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');