升級指南 · Laravel 5.2中文

[TOC] ### **從 5.1?[升級](http://laravelacademy.org/tags/%e5%8d%87%e7%ba%a7 "View all posts in 升級")到?[5.2](http://laravelacademy.org/tags/5-2 "View all posts in 5.2").0** #### **更新依賴** 更新?`composer.json`?文件指向?`laravel/framework 5.2.*`。 > 注：如果你安裝的是?[Laravel](http://laravelacademy.org/tags/laravel "View all posts in Laravel")?5.2 的 beta 版本，還要添加?`"minimum-stability": "beta"`?到`composer.json`?文件。添加?`symfony/dom-crawler ~3.0`?和?`symfony/css-selector ~3.0`?到?`composer.json`?的?`require-dev`?部分。 #### **認證** **配置文件** 更新?`config/auth.php`?文件內容如下： [https://github.com/laravel/laravel/blob/develop/config/auth.php](https://github.com/laravel/laravel/blob/develop/config/auth.php) 更新完成后，基于原來的配置設置認證選項，如果不做改動，認證服務將基于 Laravel 5.1。在新的?`auth.php`?配置文件中，要特別注意?`passwords.users.email`?配置項，由于在 Laravel 5.2 對?`email`?視圖路徑有所改動，因此要確保該視圖路徑與應用實際的路徑相匹配，如果不匹配的話要更新該配置值。 **Contracts** 如果你實現了?`Illuminate\Contracts\Auth\Authenticatable`?契約但沒有使用?`Authenticatable`?trait，那么需要添加一個新的?`getAuthIdentifierName`?方法到該契約實現類。通常，該方法返回認證實體的主鍵字段名，如：`id`。這對你的應用沒有什么影響，除非你手動實現了?`Illuminate\Contracts\Auth\Authenticatable`。 **自定義驅動** 如果你使用了?`Auth::extend`?方法自定義獲取用戶的方法，現在需要使用?`Auth::provider`?來自定義用戶提供者。一旦你自定義了提供者，就要在新的?`auth.php`?配置文件中的?`providers`?數組中配置該提供者。更多自定義認證提供者詳情，請查看其對應[文檔](http://laravel.com/docs/5.2/authentication)。 #### **授權** `Illuminate\Auth\Access\UnauthorizedException`?被重命名為`Illuminate\Auth\Access\AuthorizationException`。如果你沒有手動捕獲該異常那么這一改變對之前代碼沒有什么影響。 #### **集合** **Eloquent集合基類** 調用 Eloquent 集合實例的?`pluck`,?`keys`,?`zip`,?`collapse`,?`flatten`,?`flip`?方法現在會返回集合基類。 **保留鍵名** `slice`、`chunk`?和?`reverse`?方法現在會保留集合的鍵名，如果你不想這些方法保留鍵名，使用集合實例的?`values`方法即可。 #### **Composer類** `Illuminate\Foundation\Support\Composer`?類現在被移動到?`Illuminate\Support\Composer`，如果你沒有在代碼中使用該類那么這一改變對程序沒有影響。 #### **命令和處理器** **自處理命令** 在創建任務/命令時你不再需要實現?`SelfHandling`?契約，所有任務現在默認都是自處理的，因此你可以在自己的類中移除該接口。 **獨立的命令&處理器** Laravel 5.2 命令現在只支持自處理命令，不再支持獨立的命令和處理器。如果你想要繼續使用獨立的命令和處理器，可以安裝提供向后兼容支持的 Laravel Collective 包：[https://github.com/LaravelCollective/bus](https://github.com/LaravelCollective/bus) #### **配置** **開發環境** 添加一個?`env`?配置項到配置文件?`app.php`?中： ~~~ 'env' => env('APP_ENV', 'production'), ~~~ **緩存和環境** 如果你在開發過程中使用?`config:cache`?命令，必須保證只是在配置文件中調用了?`env`?函數，而不是在應用程序的其它地方。如果你在應用程序中調用了?`env`?函數，強烈建議添加適當的配置值到配置文件，然后在該位置調用?`env`，從而允許你將?`env`?調用改為?`config`?調用。 #### **CSRF驗證** 在單元測試中不再支持自動進行 CSRF 驗證，當然這一改變對你的應用程序代碼沒什么影響。 #### **Elixir** PHP 的?`elixir`?方法現在返回一個完整 URL 而不是相對 URL，這對應用程序沒有什么影響，除非你曾經手動將這些 URL 轉化成完整 URL。 #### **Eloquent** **日期轉化** 當調用模型或模型集合的?`toArray`?方法時，任何添加到?`$casts`?的屬性，如?`date`?或?`datetime`，現在都會被轉化為字符串。這使得在?`$dates`?數組中制定的日期轉化變得簡單方便。 **全局作用域** 我們重寫了全局作用域的實現以便于使用，全局作用域不再需要?`remove`?方法，因此可以在所有你使用到該方法的地方將其移除。如果你曾經在 Eloquent 查詢構建器上調用過了?`getQuery`?方法以獲取底層查詢構建器實例，現在應該改為調用?`toBase`?方法。如果你因為某種原因直接調用了?`remove`?方法，需要將其改成?`$eloquentBuilder->withoutGlobalScope($scope)`這種方式來調用。在 Eloquent 查詢構建器中新增了?`withoutGlobalScope`?和?`withoutGlobalScopes`?方法，任何調用?`$model->removeGlobalScopes($builder)`?的地方現在都要改成 ?`$builder->withoutGlobalScopes()`。 #### **事件** **核心事件對象** Laravel 的一些核心事件觸發現在使用事件對象取代之前的事件名稱以及動態參數，下面是原來的事件名稱與現在的事件對象對應關系： | Old | New | | --- | --- | | `auth.attempting` | `Illuminate\Auth\Events\Attempting` | | `auth.login` | `Illuminate\Auth\Events\Login` | | `auth.logout` | `Illuminate\Auth\Events\Logout` | | `cache.missed` | `Illuminate\Cache\Events\CacheMissed` | | `cache.hit` | `Illuminate\Cache\Events\CacheHit` | | `cache.write` | `Illuminate\Cache\Events\KeyWritten` | | `cache.delete` | `Illuminate\Cache\Events\KeyForgotten` | | `connection.{name}.beginTransaction` | `Illuminate\Database\Events\TransactionBeginning` | | `connection.{name}.committed` | `Illuminate\Database\Events\TransactionCommitted` | | `connection.{name}.rollingBack` | `Illuminate\Database\Events\TransactionRolledBack` | | `illuminate.query` | `Illuminate\Database\Events\QueryExecuted` | | `illuminate.queue.after` | `Illuminate\Queue\Events\JobProcessed` | | `illuminate.queue.failed` | `Illuminate\Queue\Events\JobFailed` | | `illuminate.queue.stopping` | `Illuminate\Queue\Events\WorkerStopping` | | `mailer.sending` | `Illuminate\Mail\Events\MessageSending` | | `router.matched` | `Illuminate\Routing\Events\RouteMatched` | 這些事件對象傳入參數和 Laravel 5.1 的事件處理器一樣，例如，如果你在 Laravel 5.1 中使用了?`DB:listen`?事件，在 5.2 中更新代碼如下： ~~~ DB::listen(function ($event) { dump($event->sql); dump($event->bindings); }); ~~~ 你可以去檢查每個事件對象類去查看它們的公有屬性。 #### **異常處理** `App\Exceptions\Handler`?類的?`$dontReport`?屬性應該被更新為至少包含以下異常類型的其中一個： ~~~ use Illuminate\Auth\Access\AuthorizationException; use Illuminate\Database\Eloquent\ModelNotFoundException; use Symfony\Component\HttpKernel\Exception\HttpException; use Illuminate\Foundation\Validation\ValidationException; /** * A list of the exception types that should not be reported. * * @var array */ protected $dontReport = [ AuthorizationException::class, HttpException::class, ModelNotFoundException::class, ValidationException::class, ]; ~~~ #### **隱式模型綁定** Laravel 5.2 支持“隱式模型綁定”，以便在路由和控制器中基于 URI 標識符自動注入模型實例。然而，這也改變了路由和控制器中類型提示模型實例這一行為。如果你之前在路由或控制器中類型提示了模型實例，并且希望注入一個空的模型實例，那么現在應該移除這個類型提示然后在路由或控制器中直接創建一個新的模型實例；否則，Laravel 將會基于路由 URI 的標識符試圖從數據庫獲取一個已存在的模型實例。 #### **IronMQ** IronMQ 隊列驅動被移動到自己的擴展包中，不再被框架核心支持：[http://github.com/LaravelCollective/iron-queue](http://github.com/LaravelCollective/iron-queue) #### **任務/隊列** `php artisan make:job`?命令現在默認會創建一個隊列任務類，如果你想要創建一個同步任務（非隊列），在使用該命令時加上?`--sync`?選項。 #### **郵件** 郵件配置中移除了?`pretend`?選項，取而代之的，使用?`log`?郵件驅動執行和?`pretend`?同樣的功能，并且將郵件信息記錄到日志中。 #### **分頁** 為了與框架生成的其它 URL 保持一致，分頁 URL 不再包含斜杠，這一改變對應用代碼不產生任何影響。 #### **服務提供者** `Illuminate\Foundation\Providers\ArtisanServiceProvider`?從配置文件?`app.php`?的服務提供者列表中移除。 `Illuminate\Routing\ControllerServiceProvider`?從配置文件?`app.php`?的服務提供者列表中移除。 #### **Session** **數據庫Session驅動** 我們為框架編寫了新的?`database`?Session 驅動，該驅動包含更多的用戶信息，例如用戶 ID、IP 地址以及用戶代理，如果你想要繼續使用之前的?`database`?驅動，需要在配置文件?`session.php`?中指定?`legacy-database`?驅動。如果你想要使用新的驅動，還需要添加?`user_id (nullable integer)`、`ip_address (nullable string)`?以及`user_agent (text)`?列到存放 Session 的數據表中。 #### **Stringy** 框架不再內置 Stringy 庫，如果要在應用中使用，你需要通過 Composer 手動安裝。 #### **驗證** `ValidatesRequests`?trait 現在會拋出?`Illuminate\Foundation\Validation\ValidationException`?異常以取代之前的 ?`Illuminate\Http\Exception\HttpResponseException`。如果你沒有手動捕獲該異常，那么這對之前的代碼沒有影響。 #### **廢棄** 下面這些功能在 Laravel 5.2 中被廢棄，在 Laravel 5.3 中會被徹底移除： * `Illuminate\Contracts\Bus\SelfHandling`?契約 * 集合的?`lists`?方法被重命名為?`pluck`?方法。 * 隱式控制器路由?`Route::controller`?被廢棄。在路由文件中請使用明確的路由注冊。 * Laravel 5.1 的?`database`?Session驅動被重命名為?`legacy-database`。 * `Str::randomBytes`?方法被廢棄，直接使用 PHP 的?`random_bytes`?即可。 * `Str::equals`?方法被廢棄，直接使用 PHP 的?`hash_equals`?方法即可。 * `Illuminate\View\Expression`?被廢棄，使用?`Illuminate\Support\HtmlString`?即可。