**預計升級時間：10-30分鐘** # PHP Laravel 5.6 需要 PHP 7.1.3 或更高版本。 # 更新依賴 在 `composer.json` 中更新 `laravel/framework` 依賴到 `5.6.*`，更新 `fideloper/proxy` 依賴到 `~4.0`。 此外，如果你使用下以下官方擴展包，也要升級它們到最新版本： Dusk (升級到 `~3.0`) Passport (升級到 `~5.0`) Scout (升級到 `~4.0`) 當然，不要忘了檢查應用所使用的第三方擴展包是否支持 Laravel 5.6，如果需要升級的話也要更新。 ## Symfony 4 Laravel 底層使用的所有 Symfony 組件都已經升級到 Symfony `~4.0` 版本。如果你在應用代碼中使用了 Symfony 組件，需要查看 `Symfony 更新日志`以確認是否需要修改代碼。 ## PHPUnit 需要更新應用的 `phpunit/phpunit` 依賴到 `~7.0`。 # 數組 `Arr::wrap` 方法 在 Laravel 5.6 中，傳遞 `null` 到 `Arr::wrap` 方法將會返回空數組。 # Artisan `optimize` 命令 之前版本中廢棄的 `optimize` 命令已經被徹底移除。由于 PHP 自身的性能優化，`optimize` 命令已經不能給應用提供顯著的性能提升，所以，你需要從 `composer.json` 文件的 scripts 部分移除 `php artisan optimize`。 # Blade ## HTML 實體編碼 在之前版本的 Laravel 中，Blade 不會對 HTML 實體進行雙重編碼。這并不是底層 htmlspecialchars 函數的默認行為，而且會在渲染內容或傳遞內聯 JSON 內容到 JavaScript 框架時導致預期之外的結果。 在 Laravel 5.6 中，Blade 以及輔助函數 `e` 默認會對特殊字符進行雙重編碼，從而與 PHP 底層 `htmlspecialchars` 函數的默認行為保持一致。如果你想要維持不進行雙重編碼的舊狀，可以使用 `Blade::withoutDoubleEncoding` 方法： ~~~ <?php namespace App\Providers; use Illuminate\Support\Facades\Blade; use Illuminate\Support\ServiceProvider; class AppServiceProvider extends ServiceProvider { /** * Bootstrap any application services. * * @return void */ public function boot() { Blade::withoutDoubleEncoding(); } } ~~~ # 緩存 **頻率限制器 `tooManyAttempts` 方法** 該方法簽名中未使用的 `$decayMinutes` 參數被移除。如果你通過自己的實現重寫了該方法，也要從方法簽名中移除該參數。 # 數據庫 **Morph 列的索引順序** 為了獲得更好的性能，遷移方法 `morphs` 構建的列索引順序倒過來了，如果你在某個遷移中使用了 `morphs` 方法，嘗試運行該遷移的 `down` 方法時會報錯。如果應用還在開發中，可以使用 `migrate:fresh` 命令重構數據庫結構；如果應用已經上線，需要顯式傳遞索引名稱到 `morphs` 方法。 **MigrationRepositoryInterface 新增方法** `MigrationRepositoryInterface` 中新增了一個 `getMigrationsBatches` 方法。如果非常不巧你正在自定義該類的實現，需要添加這個方法的實現。你可以以框架的默認實現作為示例。 # Eloquent `getDateFormat` 方法 `getDateFormat` 方法的可見性從 `protected` 調整為 `public`。 # 哈希 **新配置文件** 所有哈希配置現在位于獨立的 `config/hashing.php` 配置文件。你可以拷貝一份默認配置文件到你的應用。大多數情況下，我們都會將 `bcrypt` 驅動作為默認驅動。不過，也支持 `argon`。 # 輔助函數 `e` 在之前版本的 Laravel 中，Blade （以及輔助函數 `e`）不會對 HTML 實體進行雙重編碼。這并不是底層 htmlspecialchars 函數的默認行為，而且會在渲染內容或傳遞內聯 JSON 內容到 JavaScript 框架時導致預期之外的結果。 在 Laravel 5.6 中，Blade 以及輔助函數 `e` 默認會對特殊字符進行雙重編碼，從而與 PHP 底層 `htmlspecialchars` 函數的默認行為保持一致。如果你想要維持不進行雙重編碼的舊狀，可以傳遞 `false` 作為第二個參數到 `e` 函數： `<?php echo e($string, false); ?>` # 日志 **新配置文件** 所有的日志配置現在都存放在獨立的 `config/logging.php` 配置文件。你可以拷貝一份默認的配置文件到你的應用然后基于應用需要進行設置。 `log` 和 `log_level` 配置項都可以從配置文件 `config/app.php` 里移除了。 `configureMonologUsing` 方法 如果你在使用 `configureMonologUsing` 方法為應用自定義 Monolog 實例，現在需要創建一個 `custom` 日志頻道。更多關于如何創建自定義頻道的信息，可以查看完整的日志文檔。 **日志 `Writer` 類** `Illuminate\Log\Writer` 類被重命名為 `Illuminate\Log\Logger`，如果你在應用的某個類中對這個類進行了顯式的類型提示作為依賴注入，需要更新該類的引用為新的類名。或者，作為替代方案，你可以考慮將類型提示調整為標準的 `Psr\Log\LoggerInterface` 接口。 **`Illuminate\Contracts\Logging\Log` 接口** 該接口已經被移除，因為它和 `Psr\Log\LoggerInterface` 接口完全重合，需要將引用它的地方都調整為 `Psr\Log\LoggerInterface` 接口。 # 郵件 **`withSwiftMessage` 回調** 在之前版本的 Laravel 中，使用 `withSwiftMessage` 注冊的 Swift 消息自定義回調函數在內容已經被編碼并添加到消息后被調用。這些回調現在在內容被添加前調用，從而允許你自定義編碼以及其他消息選項。 # 分頁 **Bootstrap 4** 分頁器生成的分頁鏈接現在默認使用 Bootstrap 4，要讓分頁器生成 Bootstrap 3 鏈接，需要在 `AppServiceProvider` 的 `boot` 方法中調用 `Paginator::useBootstrapThree` 方法： ~~~ <?php namespace App\Providers; use Illuminate\Pagination\Paginator; use Illuminate\Support\ServiceProvider; class AppServiceProvider extends ServiceProvider { /** * Bootstrap any application services. * * @return void */ public function boot() { Paginator::useBootstrapThree(); } } ~~~ # 資源 **`original` 屬性** 資源響應的 `original` 屬性現在被設置為原始模型而不是 JSON 字符串/數組。這樣在測試中就可以更好地檢查響應的模型。 # 路由 **返回新創建的模型** 從路由中直接返回新創建的 Eloquent 模型時，響應狀態碼由 `200` 調整為 `201`，如果應用的任意相應測試顯式期望 `200` 狀態碼，那么需要將它們修改為 `201`。 # 信任代理 由于信任代碼功能使用的底層 Symfony HttpFoundation 有改動，所以必須微調 `App\Http\Middleware\TrustProxies` 中間件。 `$headers` 屬性之前是個數組，現在是一個接收幾個不同值的屬性。例如，要信任所有轉發頭，需要像這樣更新 `$headers` 屬性： ~~~ use Illuminate\Http\Request; /** * The headers that should be used to detect proxies. * * @var string */ protected $headers = Request::HEADER_X_FORWARDED_ALL; ~~~ 更多關于 `$headers` 變量值的信息可以查看完整的信任代理文檔。 # 驗證 **`ValidatesWhenResolved` 接口** 為了避免和 `$request->validate()` 方法沖突，`ValidatesWhenResolved` 接口/trait 的 `validate` 方法被重命名為 `validateResolved`。 # 雜項 我們還鼓勵你查看 `laravel/laravel` 代碼倉庫的更新日志。盡管其中的很多更新不是必須的，但是你可以將應用中的這些文件與代碼倉庫保持同步。其中的一些更新已經在這篇升級指南中覆蓋到了，但是還有很多其他的小更新比如配置文件或注釋的微調，就不會一一指出。你可以通過 `GitHub 比較工具` 輕松查看變更以便選擇那些對你而言更為重要的更新。