升級指南
高度影響的更改
中度影響的更改
低影響的更改
從 9.x 版升級至 10.0 版
預計升級所需時間:10 分鐘
雖然我們已經儘可能地在本說明文件中涵蓋所有中斷性變更。不過,在 Laravel 中,有些中斷性變更存在一些比較不明顯的地方,且這些更改中幾乎不太會影響到你的專案。 想節省時間嗎?可以使用 Laravel Shift 來協助你快速升級你的專案。
相依性套件更新
受影響的可能:高
最低版本要求為 PHP 8.1.0
Laravel 現在要求的 PHP 最低版本為 8.1.0 版。
Composer 相依性套件
請在專案的 composer.json
檔案中更新下列相依性套件:
-
laravel/framework
升級為^10.0
-
spatie/laravel-ignition
升級為^2.0
或者,可選地,如果想使用 PHPUnit 10,請在專案的 phpunit.xml
設定檔中的 <coverage>
段落中刪除 processUncoveredFiles
屬性。接著,請在專案的 composer.json
檔案中更新下列相依性套件:
-
nunomaduro/collision
to^7.0
-
phpunit/phpunit
to^10.0
最後,請檢視你的專案使用的其他第三方套件,確認一下是否有使用支援 Laravel 10 的版本。
Minimum Stability
請將專案中 composer.json
檔內的 minimum-stability
設定更新為 stable
:
1"minimum-stability": "stable",
1"minimum-stability": "stable",
快取
Redis 的快取 Tag
受影響的可能性:中等
Redis 的快取 Tag 支援已被重新撰寫以提升效能與更有效率地使用儲存空間。在先前版本的 Laravel 中,當使用 Redis 作為專案的快取 Driver 時,過時的快取 Tag 會在快取中積累。
不過,為了正確地修建過時的快取 Tag,請在專案的 App\Console\Kernel
類別內排程呼叫 Laravel 中全新的 cache:prune-stale-tags
Artisan 指令:
1$schedule->command('cache:prune-stale-tags')->hourly();
1$schedule->command('cache:prune-stale-tags')->hourly();
資料庫
資料庫運算式
受影響的可能性:中等
資料庫的「Expression」(通常由 DB::raw
產生) 在 Laravel 10.x 中已被重寫,以在未來能提供更多功能。特別是,Grammer 的原始字串值現在已改用 Expression 的 getValue(Grammar $grammar)
方法來取得。現在已不再支援通過 (string)
來將 Expression 型別轉換為字串。
一般來說,這項更改應該不會影響到終端使用者的專案;不過,如果你的專案有手動使用 (string)
來將資料庫 Expression 型別轉換為字串,或是有直接在 Expression 上呼叫 __toString
方法,則請將這些程式碼更新為呼叫 getValue
方法:
1use Illuminate\Support\Facades\DB;23$expression = DB::raw('select 1');45$string = $expression->getValue(DB::connection()->getQueryGrammar());
1use Illuminate\Support\Facades\DB;23$expression = DB::raw('select 1');45$string = $expression->getValue(DB::connection()->getQueryGrammar());
Query Exception 的 Constructor
受影響的可能:非常低
Illuminate\Database\QueryException
的 Constractor 現在接受一個字串的連線名稱作為其第一個引數。若你的專案有擲回此 Exception,請對程式做出相應修改。
ULID 欄位
受影響的可能:低
在 Migration 中,若在不提供任何引數的情況下執行 ulid
方法時,該欄位的名稱現在會是 ulid
。在先前版本的 Laravel 中,在不提供引數的情況下呼叫該方法時,所建立的欄位被錯誤地命名為 uuid
:
1$table->ulid();
1$table->ulid();
若要在呼叫 ulid
方法時明確指定欄位名稱,可傳入欄位名稱給該方法:
1$table->ulid('ulid');
1$table->ulid('ulid');
Eloquent
Model 的「Dates」屬性
受影響的可能性:中等
Eloquent Model 中停止支援 (Deprecated) 的 $dates
屬性已被移除。請使用 $casts
屬性代替:
1protected $casts = [2 'deployed_at' => 'datetime',3];
1protected $casts = [2 'deployed_at' => 'datetime',3];
關聯的 getBaseQuery
方法
受影響的可能:非常低
Illuminate\Database\Eloquent\Relations\Relation
上的 getBaseQuery
方法已重新命名為 toBase
。
日誌
Monolog 3
受影響的可能:低
Laravel 的 Monologo 相依性套件已升級為 Monolog 3.x 版。若你有在專案中直接用到 Monologo,請檢視 Monolog 的升級指南。
佇列 - Queue
Bus::dispatchNow
方法
受影響的可能:低
停止支援 (Deprecated) 的 Bus::dispatchNow
與 dispatch_now
方法現已移除。請分別改用 Bus::dispatchSync
與 dispatch_sync
方法。
路由
Middleware 的別名
受影響的可能性:可選
在新的 Laravel 專案中,App\Http\Kernel
的 $routeMiddleware
屬性已被重新命名為 $middlewareAliases
以更好地反應其目的。你可以在現有的專案中重新命名此屬性。不過,重新命名這個屬性並不是必要的。
Rate Limiter 的回傳值
受影響的可能:低
在呼叫 RateLimiter::attempt
方法時,該方法現在會回傳提供給該方法閉包的回傳值。若該閉包沒有回傳值,或是回傳了 null
,則 attempt
方法會回傳 true
:
1$value = RateLimiter::attempt('key', 10, fn () => ['example'], 1);23$value; // ['example']
1$value = RateLimiter::attempt('key', 10, fn () => ['example'], 1);23$value; // ['example']
Redirect::home
方法
受影響的可能:非常低
停止支援 (Deprecated) 的 Redirect::home
方法現已被移除。請改為直接使用命名 Route 來做重新導向:
1return Redirect::route('home');
1return Redirect::route('home');
測試
Service Mock
受影響的可能性:中等
停止支援 (Deprecated) 的 MocksApplicationServices
Trait 已從 Laravel Framework 中移除。這個 Trait 提供了如 expectsEvents
、expectesJobs
、與 expectesNotifications
等的測試方法。
如果你使用到這些方法,建議分別改用 Event::fake
、Bus::fake
、與 Notification::fake
。更多有關 Mock 的資訊,可參考完整的 Mock 說明文件。
表單驗證
閉包的 Validation Rule 訊息
受影響的可能:非常低
在撰寫基於閉包的自定 Validation Rule 時,若呼叫 $fail
回呼超過一次時,原本訊息會被取代,現在改為會將訊息加到陣列的尾端。一般來說,這應該不會影響到你的專案。
此外,$fail
回呼現在會回傳一個物件。如果原本有在 Validation 閉包中 Type-Hint 回傳型別,則可能有需要更新:
1public function rules()2{3 'name' => [4 function ($attribute, $value, $fail) {5 $fail('validation.translation.key')->translate();6 },7 ],8}
1public function rules()2{3 'name' => [4 function ($attribute, $value, $fail) {5 $fail('validation.translation.key')->translate();6 },7 ],8}
其他
我們也建議你檢視 laravel/laravel
GitHub 存放庫上的更改。雖然這些更改中大多數都不是必須要進行的,但你可能也會想讓專案中的這些檔案保持同步。其中一些修改有在本升級指南中提到,但有些其他的更改 (如設定檔的更改或註解等) 就沒有提到。
你可以輕鬆地通過 GitHub 的比較工具來檢視這些更改,並自行判斷哪些修改對你來說是重要的。不過,GitHub 比較工具上顯示的許多更改都是因為 Laravel 選用了 PHP 原生型別導致的。這些更改是能向下相容的,而在升級到 Laravel 10 時,可選擇是否要加上這些原生型別提示。