# 發行說明 - [版本控制方案](#versioning-scheme) - [支持策略](#support-policy) - [Laravel 5.5](#laravel-5.5) <a name="versioning-scheme"></a> ## 版本控制方案 Laravel 的版本控制方案繼續以下約定： `主版本號.次版本號.修訂號`。次版本號的框架會在每六個月發布一次 (二月和八月)，修訂號發布可能會每周發布一次。而修訂號版本**不**應該包含破壞性更改。 當你從應用程序中或者在包中引用 Laravel 框架或其組件時，應始終使用版本約束，例如 `5.5.*`，因為 Laravel 的次版本號會包括突破性更改。但是，我們會努力確保你可以在一天或更短時間內完成更新。 主版本號之間的迭代往往需要多年，每次迭代都代表了框架的架構和底層結構發生了改變。而目前并沒有準備開發主版本號的計劃。 #### 為什么 Laravel 不使用語義版本控制？ 一方面，Laravel 所有可選的組件（Cashier、Dusk、Valet、Socialite 等等）都使用語義版本控制。然而 Laravel 框架本身并沒有這樣做。原因是語義版本控制是確定兩段代碼是否兼容的「簡化」方法。即使是使用語義版本控制，你仍然必須安裝升級包并運行你的自動化測試組建，來確定*事實上*是否有任何異常與代碼不兼容。 相反，Laravel 框架使用的版本控制方案更適合實際的發布。此外，因為修訂版本的發布**不**包含破壞性變更，只要你的版本遵循 `主版本號.次版本號.*` 的約定， 你就不會接收到破壞性變更。 <a name="support-policy"></a> ## 支持策略 對于 LTS 版本，例如 Laravel 5.1，提供兩年的錯誤修復和三年的安全修復。這些版本提供最長時間的支持和維護。對于一般版本，則只是提供六個月的錯誤修復和為期一年的安全修復。 > [Laravel 的發布路線圖](https://laravel-china.org/articles/2594/laravel-release-roadmap) - by [Summer](https://github.com/summerblue) <a name="laravel-5.5"></a> ## Laravel 5.5 Laravel 5.5 對 Laravel 5.4 種的包進行了改進，其中添加了：包自動發現、API 資源／轉換、控制臺命令自動注冊、隊列任務鏈、隊列任務速率限制、基于時間任務的嘗試、可渲染的郵件、自定義異常報告、異常處理規范化、數據庫測試改進、更簡單自定義驗證規則、前端預配置、`Route::view` 和 `Route::redirect` 方法、Memcached 和 Redis 緩存驅動程序的「鎖定」、按需通知功能、Dusk 支持 Chrome 的 headless 模式 、方便的 Blade 快捷鍵、改進可信代理支持等。 此外， Laravel 5.5 同時發布了 [Laravel Horizon](http://horizon.laravel.com)，一個用來管理你的 Redis 隊列的漂亮的隊列儀表板和配置系統。 > {tip} 這份文檔總結了最值得注意的框架變更，如果需要了解更多，請查看 [GitHub](https://github.com/laravel/framework/blob/5.5/CHANGELOG-5.5.md) 上更全面的變更日志。 ### Laravel Horizon Horizon 為你的 Laravel Redis 隊列提供了一個漂亮的儀表版和代碼驅動配置。Horizon 允許你輕松監控隊列系統的關鍵指標，例如任務吞吐量、運行時間和失敗任務。 所有的配置都存放一個簡單的配置文件中，讓你的整個團隊可以協同工作。 更多關于 Horizon 的信息，請查看 [完整的 Horizon 文檔](/docs/{{version}}/horizon)。 ### 包自動發現 在之前的 Laravel 版本中，安裝包通常需要幾個步驟，例如添加服務提供器到 `app` 配置文件并注冊相關的 facades。現在，從 Laravel 5.5 開始，Laravel 可以自動檢測并注冊服務提供器和 facades。 例如，你可以通過 `barryvdh/laravel-debugbar` 安裝這個包來體驗一下。用 Composer 來安裝之后，無需任何配置，就可以直接使用 debugbar： composer require barryvdh/laravel-debugbar 包的開發者只需要將他們的服務提供器和門面添加到他們的包的 `composer.json` 文件中： "extra": { "laravel": { "providers": [ "Laravel\\Tinker\\TinkerServiceProvider" ] } }, 更多信息，請查看詳細文檔 [包開發](/docs/{{version}}/packages). ### API 資源 構建 API 時，你可能需要一個位于 Eloquent 模型和實際返回給用戶響應之間的 JSON 轉換層。Laravel 的資源類允許你以輕松地方式將你的模型和模型集合轉換為 JSON。而這個資源類代表了需要轉換為 JSON 結構的單個模型。例如，這里是一個簡單的用戶資源類： ````php <?php namespace App\Http\Resources; use Illuminate\Http\Resources\Json\Resource; class User extends Resource { /** * 將資源轉換為數組。 * * @param \Illuminate\Http\Request * @return array */ public function toArray($request) { return [ 'id' => $this->id, 'name' => $this->name, 'email' => $this->email, 'created_at' => $this->created_at, 'updated_at' => $this->updated_at, ]; } } ```` 當然這只是 API 資源的最基本的例子。 Laravel 還提供各種方法來幫助你構建資源和資源集合。有關更多信息，請查看有關 API 資源的 [完整文檔](/docs/{{version}}/eloquent-resources)。 ### 控制臺命令自動注冊 當創建一個新的控制臺命令，不再需要必須手動把它們列入到你的控制臺內核的 `$commands` 屬性中。在內核的 `commands` 方法中調用一個新的 `load` 方法，它會掃描給定的目錄來獲取控制臺命令并自動注冊它們： /** * 注冊應用程序的命令。 * * @return void */ protected function commands() { $this->load(__DIR__.'/Commands'); // ... } ### 新前端預配置 雖然基礎的 Vue 腳手架依然包含在 Laravel 5.5 中，不同的是，現在有了幾種新的前端預設選項可用的。一個新的 Laravel 應用中，你可以使用 `preset` 命令將 Vue 腳手架更換為 React 腳手架： php artisan preset react 或者，你可以使用 `preset none` 完全刪除 JavaScript 和 CSS 框腳手架。這個預設配置會為你的應用提供簡單的 Sass 文件和實用的 JavaScript： php artisan preset none > {note} 這個命令只能用在新創建的框架中，而不應該在現有的應用中使用它。 ### 隊列任務鏈 任務鏈允許你指定按順序運行的隊列任務列表。如果隊列中的一個任務失敗，則其余任務便不會再運行。要執行隊列的任務鏈，你可以在分配任務時使用 `withChain` 方法： ProvisionServer::withChain([ new InstallNginx, new InstallPhp ])->dispatch(); ### Queued 任務速率限制 如果你的應用程序與 Redis 進行交互，那你就可以根據時間或并發來調整排隊的任務。當你隊列的任務與限制速率的 API 進行交互時，這個功能就派上用場了。例如，你可以限制給定類型的任務只能每 60 秒運行 10 次： ````Php Redis::throttle('key')->allow(10)->every(60)->then(function () { // 任務邏輯... }, function () { // 無法獲得鎖... return $this->release(10); }); ```` > {tip} 在上面的示例中，`key` 是唯一可以標識要限制的任務類型的字符串。 例如，你可能會根據任務的類名和其運行的 Eloquent 模型的 ID 來構建這個 key。 或者，你也可以指定同時處理給定任務的最大工作進程數。當隊列的任務正在修改一次只能由一個任務修改的資源時，我們可以將給定類型的任務限制為一次只能由一個工作進程處理： ````Php Redis::funnel('key')->limit(1)->then(function () { // 任務邏輯... }, function () { // 無法獲得鎖... return $this->release(10); }); ```` ### 基于時間的任務嘗試 作為在任務失敗之前定義任務可能嘗試多少次的替代方法，現在你可以定義任務的超時時間。這允許在給定時間范圍內嘗試次數的任務。將 `retryUntil` 方法添加到任務類中來定義任務的超時時間： ````Php /** * 確定任務的超時時間。 * * @return \DateTime */ public function retryUntil() { return now()->addSeconds(5); } ```` > {tip} 你也可以在隊列的事件監聽器上定義一個 `retryUntil` 方法。 ### 驗證規則對象 驗證規則對象為你的應用程序提供了一種新的、緊湊的方式來添加自定義驗證規則。在以前的 Laravel 版本中，`Validator::extend` 方法用于通過閉包添加自定義驗證規則。但是，某種程度上這樣挺麻煩的。在 Laravel 5.5 中，可以用新的 Artisan 命令 `make:rule` 在 `app/Rules` 目錄中創建一個新的驗證規則： php artisan make:rule ValidName 驗證對象只有兩個方法：`passes` 和 `message`。`passes` 方法接收屬性值和名稱，并根據屬性值是否有效返回 `true` 或 `false`。`message` 方法返回驗證失敗時應使用的驗證錯誤消息： <?php namespace App\Rules; use Illuminate\Contracts\Validation\Rule; class ValidName implements Rule { /** * 確定驗證規則是否通過 * * @param string $attribute * @param mixed $value * @return bool */ public function passes($attribute, $value) { return strlen($value) === 6; } /** * 獲取驗證錯誤信息 * * @return string */ public function message() { return 'The name must be six characters long.'; } } 一旦定義了規則，你就可以簡單地通過傳遞一個規則對象的實例與其他驗證規則來使用它： use App\Rules\ValidName; $this->validate($request, [ 'name' => ['required', new ValidName], ]); ### 可信代理集成 在應用程序后面的負載均衡器上運行到期的 TLS / SSL 證書時，你會注意到你的應用有時不能創建 HTTPS 鏈接。這通常是因為你的應用正在從 80 端口轉發流量的負載均衡器不知道安全鏈接應該被生成。 為了解決這個問題，很多 Laravel 用戶安裝了Chris Fidao 的包 [Trusted Proxies](https://github.com/fideloper/TrustedProxy) 。因為這是一個常見情況，Chris 的包現在已經默認集成在 Laravel 5.5 中了。 默認情況下，Lravel 5.5 中包含了一個新的中間件 `App\Http\Middleware\TrustProxies`。這個中間件允許你快速自定義受信任的代理： <?php namespace App\Http\Middleware; use Illuminate\Http\Request; use Fideloper\Proxy\TrustProxies as Middleware; class TrustProxies extends Middleware { /** * 這個應用程序的可信代理 * * @var array */ protected $proxies; /** * 當前的代理頭映射 * * @var array */ protected $headers = [ Request::HEADER_FORWARDED => 'FORWARDED', Request::HEADER_X_FORWARDED_FOR => 'X_FORWARDED_FOR', Request::HEADER_X_FORWARDED_HOST => 'X_FORWARDED_HOST', Request::HEADER_X_FORWARDED_PORT => 'X_FORWARDED_PORT', Request::HEADER_X_FORWARDED_PROTO => 'X_FORWARDED_PROTO', ]; } ### 按需通知 有時候你可能需要發送通知給不在應用中存儲的 「用戶」，使用新的 `Notification::route` 方法，你可以在發送之前指定臨時的路由信息： Notification::route('mail', 'taylor@laravel.com') ->route('nexmo', '5555555555') ->send(new InvoicePaid($invoice)); ### 可渲染的郵件 現在可直接從路由返回郵件，讓你可以在瀏覽器快速預覽你的郵件樣式： Route::get('/mailable', function () { $invoice = App\Invoice::find(1); return new App\Mail\InvoicePaid($invoice); }); ### 自定義異常報告 在之前的 Laravel 版本中，你可能不得不在異常處理程序中使用「類型檢查」，來為給定異常呈現自定義響應。例如，你可能有在處理異常程序的 `render` 方法中寫了這樣的代碼： /** * 渲染異常信息給一個 HTTP 響應 * * @param \Illuminate\Http\Request $request * @param \Exception $exception * @return \Illuminate\Http\Response */ public function render($request, Exception $exception) { if ($exception instanceof SpecialException) { return response(...); } return parent::render($request, $exception); } 在 Laravel 5.5 中，你可以直接在異常中定義一個 `render` 方法。這個方法允許你將自定義響應呈現邏輯直接放置在異常上來避免異常處理程序中的條件邏輯積累。如果你想要自定義異常的報告邏輯，你可以在這個類中定義 `report` 方法： <?php namespace App\Exceptions; use Exception; class SpecialException extends Exception { /** * 報告異常 * * @return void */ public function report() { // } /** * 渲染異常 * * @param \Illuminate\Http\Request * @return void */ public function render($request) { return response(...); } } ### 請求驗證 `Illuminate\Http\Request` 對象現在提供一個 `validate` 方法, 允許你快速驗證傳入路由閉包或控制器的請求： use Illuminate\Http\Request; Route::get('/comment', function (Request $request) { $request->validate([ 'title' => 'required|string', 'body' => 'required|string', ]); // ... }); ### 異常處理規范化 現在在整個框架中，驗證異常處理的響應消息是一致的。以前，框架中有多個位置需要將默認的驗證錯誤響應的 JSON 格式更改為自定義。現在，Laravel 5.5 中驗證響應默認 JSON 格式現在遵守以下約定： { "message": "The given data was invalid.", "errors": { "field-1": [ "Error 1", "Error 2" ], "field-2": [ "Error 1", "Error 2" ], } } 所有驗證錯誤的 JSON 格式可以通過在 `App\Exceptions\Handler` 類中定義單個方法來控制。例如，下面將使用 Laravel 5.4 方式進行來自定義驗證響應的 JSON 格式： use Illuminate\Validation\ValidationException; /** * 將驗證異常轉換為 JSON 響應 * * @param \Illuminate\Http\Request $request * @param \Illuminate\Validation\ValidationException $exception * @return \Illuminate\Http\JsonResponse */ protected function invalidJson($request, ValidationException $exception) { return response()->json($exception->errors(), $exception->status); } ### 緩存鎖 Redis 和 Memcached 緩存驅動程序現在支持獲取和釋放原子「鎖」。這提供了一種在不考慮競爭條件的情況下獲取任意鎖的簡單方法。舉個例子，在執行任務之前，你可能希望獲得給定值的鎖定，來確保沒有其他進程在執行相同的任務： if (Cache::lock('lock-name', 60)->get()) { // 獲得鎖 60 秒，繼續處理…… Cache::lock('lock-name')->release(); } else { // 無法獲得鎖…… } 或者，你可以將給 `get` 方法傳遞一個閉包。在判斷可以鎖定給定值并且在執行閉包后自動釋放鎖定的情況下，閉包才會執行： Cache::lock('lock-name', 60)->get(function () { // 獲得鎖 60 秒 }); 此外，你也可以直接對給定值進行 「阻塞」直到鎖可用為止: if (Cache::lock('lock-name', 60)->block(10)) { // 等待最長10秒的時間，鎖可用 } ### Blade 改進 編寫一個自定義指令有時候比定義簡單的自定義條件語句更復雜。因此 Blade 現在提供一個 `Blade::if` 方法，它允許你使用閉包快速定義自定義條件指令。舉個例子，定義一個檢查當前應用程序環境的自定義條件，我們可以在我們的 `AppServiceProvider` 的 `boot` 方法這樣做： use Illuminate\Support\Facades\Blade; /** * 執行注冊后引導服務 * * @return void */ public function boot() { Blade::if('env', function ($environment) { return app()->environment($environment); }); } 定義完之后，你可以在模版中這樣使用： @env('local') // 應用是本地環境... @else // 應用不是本地環境... @endenv 除了能夠輕松定義 Blade 條件指令之外，5.5 還添加了指令 `@auth` 和 `@guest` 來快速檢查當前用戶的身份驗證狀態： @auth // 當前用戶已經登錄... @endauth @guest // 當前用戶未登錄... @endguest ### 新路由方法 如果要定義重定向到另一個 URI 的路由，可以使用 `Route::redirect` 方法。這個方法算是一種快捷方式。這樣你就不必定義完整的路由或控制器來執行簡單的重定向： Route::redirect('/here', '/there', 301); 同樣的效果，如果你的路由只需要返回一個視圖，使用 `Route::view` 方法。`view` 方法接受一個 URI 作為第一個參數，視圖名稱作為其第二個參數。另外，你可以提供一個數組作為可選的第三個參數傳遞給視圖： Route::view('/welcome', 'welcome'); Route::view('/welcome', 'welcome', ['name' => 'Taylor']); ### 「Sticky」數據庫連接 #### `sticky` 選項 配置讀／寫數據庫連接時，可以使用新的 `sticky` 配置選項： ```` 'mysql' => [ 'read' => [ 'host' => '192.168.1.1', ], 'write' => [ 'host' => '196.168.1.2' ], 'sticky' => true, 'driver' => 'mysql', 'database' => 'database', 'username' => 'root', 'password' => '', 'charset' => 'utf8mb4', 'collation' => 'utf8mb4_unicode_ci', 'prefix' => '', ], ```` `sticky` 選項是一個可選的值，可用于在當前請求周期內立即讀取已寫入數據庫的記錄。如果啟用了 `sticky` 選項，并且在當前請求周期內對數據庫執行了「寫入」操作，任何進一步的「讀取」操作將使用「寫入」連接。這確保了在該請求周期期間寫入的任何數據可以在同一請求期間立即從數據庫讀回。你可以決定這是否是你應用程序所需的行為。 ## 譯者署名 | 用戶名 | 頭像 | 職能 | 簽名 | |---|---|---|---| | [@dongm2ez](https://github.com/dongm2ez) | <img class="avatar-66 rm-style" src="https://avatars3.githubusercontent.com/u/9032795?v=3&s=460?imageView2/1/w/100/h/100"> | 翻譯 | 歡迎在 [Github](https://github.com/dongm2ez) 上關注我 | | [@JokerLinly](https://laravel-china.org/users/5350) | <img class="avatar-66 rm-style" src="https://dn-phphub.qbox.me/uploads/avatars/5350_1481857380.jpg"> | Review | Stay Hungry. Stay Foolish. | --- > {note} 歡迎任何形式的轉載，但請務必注明出處，尊重他人勞動共創開源社區。 > > 轉載請注明：本文檔由 Laravel China 社區 [laravel-china.org](https://laravel-china.org) 組織翻譯，詳見 [翻譯召集帖](https://laravel-china.org/topics/5756/laravel-55-document-translation-call-come-and-join-the-translation)。 > > 文檔永久地址： https://d.laravel-china.org