升級指南

• 從 9.x 版升級至 10.0 版

高度影響的更改

中度影響的更改

低影響的更改

從 9.x 版升級至 10.0 版

預計升級所需時間：10 分鐘

相依性套件更新

受影響的可能：高

最低版本要求為 PHP 8.1.0

Laravel 現在要求的 PHP 最低版本為 8.1.0 版。

Composer 相依性套件

請在專案的 composer.json 檔案中更新下列相依性套件：

或者，可選地，如果想使用 PHPUnit 10，請在專案的 phpunit.xml 設定檔中的 <coverage> 段落中刪除 processUncoveredFiles 屬性。接著，請在專案的 composer.json 檔案中更新下列相依性套件：

最後，請檢視你的專案使用的其他第三方套件，確認一下是否有使用支援 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;
2 
3$expression = DB::raw('select 1');
4 
5$string = $expression->getValue(DB::connection()->getQueryGrammar());
1use Illuminate\Support\Facades\DB;
2 
3$expression = DB::raw('select 1');
4 
5$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。

本土化

語系檔目錄

受影響的可能：無

雖然與現有專案無關，不過 Laravel 的專案 Skeleton 現在預設不包含 lang 目錄。在撰寫新的 Laravel 專案時，可以使用 lang:publish Artisan 指令來安裝該目錄：

1php artisan lang:publish
1php artisan lang:publish

日誌

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);
2 
3$value; // ['example']
1$value = RateLimiter::attempt('key', 10, fn () => ['example'], 1);
2 
3$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 時，可選擇是否要加上這些原生型別提示。