升級指南

如果您的應用程式使用 Laravel Cashier Stripe、Passport、Sanctum、Spark Stripe 或 Telescope，您將需要將它們的遷移發佈到您的應用程式。Cashier Stripe、Passport、Sanctum、Spark Stripe 和 Telescope **不再自動從它們自己的遷移**目錄載入遷移。因此，您應該執行以下命令將它們的遷移發佈到您的應用程式

php artisan vendor:publish --tag=cashier-migrations
php artisan vendor:publish --tag=passport-migrations
php artisan vendor:publish --tag=sanctum-migrations
php artisan vendor:publish --tag=spark-migrations
php artisan vendor:publish --tag=telescope-migrations

此外，您應該檢閱每個套件的升級指南，以確保您了解任何額外的重大變更

Laravel Cashier Stripe
Laravel Passport
Laravel Sanctum
Laravel Spark Stripe
Laravel Telescope

如果您手動安裝了 Laravel 安裝程式，您應該透過 Composer 更新安裝程式

composer global require laravel/installer:^5.6

最後，如果先前已將 doctrine/dbal Composer 相依性新增至您的應用程式，您可以移除它，因為 Laravel 不再相依於此套件。

應用程式結構

Laravel 11 引入了新的預設應用程式結構，其中預設檔案較少。也就是說，新的 Laravel 應用程式包含較少的服務提供者、中介層和設定檔案。

但是，我們**不建議**將 Laravel 10 應用程式升級到 Laravel 11 時嘗試遷移其應用程式結構，因為 Laravel 11 已仔細調整為也支援 Laravel 10 的應用程式結構。

身份驗證

密碼重新雜湊

影響可能性：低

如果您的雜湊演算法的「工作因素」自上次雜湊密碼後已更新，Laravel 11 將在驗證期間自動重新雜湊您使用者的密碼。

通常，這不應中斷您的應用程式；但是，如果您的 User 模型的「密碼」欄位名稱不是 password，您應該透過模型的 authPasswordName 屬性指定欄位的名稱

protected $authPasswordName = 'custom_password_field';

或者，您可以透過將 rehash_on_login 選項新增至應用程式的 config/hashing.php 設定檔來停用密碼重新雜湊

'rehash_on_login' => false,

`UserProvider` 合約

影響可能性：低

Illuminate\Contracts\Auth\UserProvider 合約已收到新的 rehashPasswordIfRequired 方法。此方法負責在應用程式的雜湊演算法工作因素變更時，重新雜湊並將使用者的密碼儲存在儲存空間中。

如果您的應用程式或套件定義了實作此介面的類別，您應該將新的 rehashPasswordIfRequired 方法新增至您的實作。參考實作可以在 Illuminate\Auth\EloquentUserProvider 類別中找到

public function rehashPasswordIfRequired(Authenticatable $user, array $credentials, bool $force = false);

`Authenticatable` 合約

影響可能性：低

Illuminate\Contracts\Auth\Authenticatable 合約已收到新的 getAuthPasswordName 方法。此方法負責傳回您的可驗證實體的密碼欄位名稱。

如果您的應用程式或套件定義了實作此介面的類別，您應該將新的 getAuthPasswordName 方法新增至您的實作

public function getAuthPasswordName()
{
    return 'password';
}

Laravel 隨附的預設 User 模型會自動收到此方法，因為此方法包含在 Illuminate\Auth\Authenticatable trait 中。

`AuthenticationException` 類別

影響可能性：非常低

Illuminate\Auth\AuthenticationException 類別的 redirectTo 方法現在需要 Illuminate\Http\Request 實例作為其第一個引數。如果您手動捕獲此例外並呼叫 redirectTo 方法，您應該相應地更新您的程式碼

if ($e instanceof AuthenticationException) {
    $path = $e->redirectTo($request);
}

註冊時的電子郵件驗證通知

影響可能性：非常低

如果您的應用程式的 EventServiceProvider 尚未註冊 SendEmailVerificationNotification 監聽器，則現在會針對 Registered 事件自動註冊該監聽器。如果您的應用程式的 EventServiceProvider 沒有註冊此監聽器，而且您不希望 Laravel 自動為您註冊，您應該在應用程式的 EventServiceProvider 中定義一個空的 configureEmailVerification 方法

protected function configureEmailVerification()
{
    // ...
}

快取

快取鍵字首

影響可能性：非常低

先前，如果為 DynamoDB、Memcached 或 Redis 快取儲存定義了快取鍵字首，Laravel 會在字首後面加上 :。在 Laravel 11 中，快取鍵字首不會收到 : 後綴。如果您想要維持先前的字首行為，您可以手動將 : 後綴新增至快取鍵字首。

集合

`Enumerable` 合約

影響可能性：低

Illuminate\Support\Enumerable 合約的 dump 方法已更新為接受可變引數 ...$args。如果您正在實作此介面，您應該相應地更新您的實作

public function dump(...$args);

資料庫

SQLite 3.26.0+

影響可能性：高

如果您的應用程式使用 SQLite 資料庫，則需要 SQLite 3.26.0 或更高版本。

Eloquent 模型 `casts` 方法

影響可能性：低

基本 Eloquent 模型類別現在定義了 casts 方法，以支援屬性轉換的定義。如果您的應用程式的其中一個模型正在定義 casts 關係，它可能會與現在存在於基本 Eloquent 模型類別上的 casts 方法衝突。

修改欄位

影響可能性：高

修改欄位時，您現在必須明確包含變更後要保留在欄位定義上的所有修飾符。任何遺失的屬性都將被丟棄。例如，若要保留 unsigned、default 和 comment 屬性，您必須在變更欄位時明確呼叫每個修飾符，即使這些屬性已由先前的遷移指派給欄位。

舉例來說，假設您有一個遷移檔案建立了名為 votes 的欄位，並帶有 unsigned、default 和 comment 屬性。

Schema::create('users', function (Blueprint $table) {
    $table->integer('votes')->unsigned()->default(1)->comment('The vote count');
});

稍後，您撰寫另一個遷移檔案將此欄位改為 nullable。

Schema::table('users', function (Blueprint $table) {
    $table->integer('votes')->nullable()->change();
});

在 Laravel 10 中，這個遷移檔案會保留欄位上的 unsigned、default 和 comment 屬性。然而，在 Laravel 11 中，遷移檔案現在也必須包含先前定義在欄位上的所有屬性。否則，它們將會被移除。

Schema::table('users', function (Blueprint $table) {
    $table->integer('votes')
        ->unsigned()
        ->default(1)
        ->comment('The vote count')
        ->nullable()
        ->change();
});

change 方法不會變更欄位的索引。因此，您可以使用索引修飾符來在修改欄位時明確地新增或移除索引。

// Add an index...
$table->bigIncrements('id')->primary()->change();
 
// Drop an index...
$table->char('postal_code', 10)->unique(false)->change();

如果您不希望更新應用程式中所有現有的「change」遷移檔案以保留欄位的現有屬性，您可以簡單地壓縮您的遷移檔案。

php artisan schema:dump

一旦您的遷移檔案被壓縮，Laravel 將會在執行任何待處理的遷移檔案之前，先使用您應用程式的綱要檔案「遷移」資料庫。

浮點數類型

影響可能性：高

double 和 float 遷移欄位類型已被重寫，以在所有資料庫中保持一致。

double 欄位類型現在會建立一個等同於 DOUBLE 的欄位，而沒有總位數和小數位數（小數點後的位數），這是標準的 SQL 語法。因此，您可以移除 $total 和 $places 的參數。

$table->double('amount');

float 欄位類型現在會建立一個等同於 FLOAT 的欄位，而沒有總位數和小數位數（小數點後的位數），但可以使用選用的 $precision 規格來決定儲存大小，分為 4 位元組的單精度欄位或 8 位元組的雙精度欄位。因此，您可以移除 $total 和 $places 的參數，並根據您資料庫的文件將選用的 $precision 指定為您想要的值。

$table->float('amount', precision: 53);

unsignedDecimal、unsignedDouble 和 unsignedFloat 方法已被移除，因為這些欄位類型的不帶正負號修飾符已被 MySQL 棄用，並且從未在其他資料庫系統上標準化。然而，如果您希望繼續使用這些欄位類型已棄用的不帶正負號屬性，您可以在欄位的定義上鏈接 unsigned 方法。

$table->decimal('amount', total: 8, places: 2)->unsigned();
$table->double('amount')->unsigned();
$table->float('amount', precision: 53)->unsigned();

專用的 MariaDB 驅動程式

影響可能性：非常低

Laravel 11 新增了專用於 MariaDB 的資料庫驅動程式，而不是在連線到 MariaDB 資料庫時總是使用 MySQL 驅動程式。

如果您的應用程式連線到 MariaDB 資料庫，您可以將連線設定更新為新的 mariadb 驅動程式，以便未來受益於 MariaDB 特有的功能。

'driver' => 'mariadb',
'url' => env('DB_URL'),
'host' => env('DB_HOST', '127.0.0.1'),
'port' => env('DB_PORT', '3306'),
// ...

目前，新的 MariaDB 驅動程式的行為與目前的 MySQL 驅動程式類似，只有一個例外：uuid 綱要建立器方法會建立原生 UUID 欄位，而不是 char(36) 欄位。

如果您的現有遷移檔案使用了 uuid 綱要建立器方法，並且您選擇使用新的 mariadb 資料庫驅動程式，您應該將遷移檔案中對 uuid 方法的調用更新為 char，以避免破壞性變更或意外行為。

Schema::table('users', function (Blueprint $table) {
    $table->char('uuid', 36);
 
    // ...
});

空間類型

影響可能性：低

資料庫遷移的空間欄位類型已被重寫，以在所有資料庫中保持一致。因此，您可以從您的遷移檔案中移除 point、lineString、polygon、geometryCollection、multiPoint、multiLineString、multiPolygon 和 multiPolygonZ 方法，並改用 geometry 或 geography 方法。

$table->geometry('shapes');
$table->geography('coordinates');

若要在 MySQL、MariaDB 和 PostgreSQL 上明確限制儲存在欄位中的值的類型或空間參考系統識別碼，您可以將 subtype 和 srid 傳遞給方法。

$table->geometry('dimension', subtype: 'polygon', srid: 0);
$table->geography('latitude', subtype: 'point', srid: 4326);

PostgreSQL 語法的 isGeometry 和 projection 欄位修飾符已相應移除。

移除 Doctrine DBAL

影響可能性：低

以下 Doctrine DBAL 相關的類別和方法已被移除。Laravel 不再依賴此套件，並且不再需要註冊自訂 Doctrine 類型，才能正確建立和變更先前需要自訂類型的各種欄位類型。

Illuminate\Database\Schema\Builder::$alwaysUsesNativeSchemaOperationsIfPossible 類別屬性
Illuminate\Database\Schema\Builder::useNativeSchemaOperationsIfPossible() 方法
Illuminate\Database\Connection::usingNativeSchemaOperations() 方法
Illuminate\Database\Connection::isDoctrineAvailable() 方法
Illuminate\Database\Connection::getDoctrineConnection() 方法
Illuminate\Database\Connection::getDoctrineSchemaManager() 方法
Illuminate\Database\Connection::getDoctrineColumn() 方法
Illuminate\Database\Connection::registerDoctrineType() 方法
Illuminate\Database\DatabaseManager::registerDoctrineType() 方法
Illuminate\Database\PDO 目錄
Illuminate\Database\DBAL\TimestampType 類別
Illuminate\Database\Schema\Grammars\ChangeColumn 類別
Illuminate\Database\Schema\Grammars\RenameColumn 類別
Illuminate\Database\Schema\Grammars\Grammar::getDoctrineTableDiff() 方法

此外，不再需要在應用程式的 database 設定檔中使用 dbal.types 註冊自訂 Doctrine 類型。

如果您先前使用 Doctrine DBAL 來檢查您的資料庫及其相關資料表，您可以使用 Laravel 新的原生綱要方法（Schema::getTables()、Schema::getColumns()、Schema::getIndexes()、Schema::getForeignKeys() 等）來取代。

已棄用的綱要方法

影響可能性：非常低

已棄用、基於 Doctrine 的 Schema::getAllTables()、Schema::getAllViews() 和 Schema::getAllTypes() 方法已被移除，並改用新的 Laravel 原生 Schema::getTables()、Schema::getViews() 和 Schema::getTypes() 方法。

當使用 PostgreSQL 和 SQL Server 時，新的綱要方法都不會接受三部分參考（例如 database.schema.table）。因此，您應該使用 connection() 來宣告資料庫。

Schema::connection('database')->hasTable('schema.table');

綱要建立器 `getColumnType()` 方法

影響可能性：非常低

Schema::getColumnType() 方法現在總是會傳回給定欄位的實際類型，而不是 Doctrine DBAL 等效類型。

資料庫連線介面

影響可能性：非常低

Illuminate\Database\ConnectionInterface 介面已收到一個新的 scalar 方法。如果您要定義此介面自己的實作，您應該將 scalar 方法新增到您的實作中。

public function scalar($query, $bindings = [], $useReadPdo = true);

日期

Carbon 3

影響的可能性：中等

Laravel 11 支援 Carbon 2 和 Carbon 3。Carbon 是一個日期操作函式庫，被 Laravel 和整個生態系統的套件廣泛使用。如果您升級到 Carbon 3，請注意 diffIn* 方法現在會傳回浮點數，並且可能會傳回負值以表示時間方向，這與 Carbon 2 有顯著的差異。請參閱 Carbon 的變更記錄和文件，以取得有關如何處理這些和其他變更的詳細資訊。

郵件

`Mailer` 契約

影響可能性：非常低

Illuminate\Contracts\Mail\Mailer 契約已收到一個新的 sendNow 方法。如果您的應用程式或套件正在手動實作此契約，您應該將新的 sendNow 方法新增到您的實作中。

public function sendNow($mailable, array $data = [], $callback = null);

套件

將服務提供者發佈到應用程式

影響可能性：非常低

如果您編寫了一個 Laravel 套件，該套件會手動將服務提供者發佈到應用程式的 app/Providers 目錄，並手動修改應用程式的 config/app.php 設定檔以註冊服務提供者，您應該更新您的套件以使用新的 ServiceProvider::addProviderToBootstrapFile 方法。

addProviderToBootstrapFile 方法會自動將您已發佈的服務提供者新增到應用程式的 bootstrap/providers.php 檔案中，因為新的 Laravel 11 應用程式中的 config/app.php 設定檔中不存在 providers 陣列。

use Illuminate\Support\ServiceProvider;
 
ServiceProvider::addProviderToBootstrapFile(Provider::class);

佇列

`BatchRepository` 介面

影響可能性：非常低

Illuminate\Bus\BatchRepository 介面已收到一個新的 rollBack 方法。如果您要在自己的套件或應用程式中實作此介面，您應該將此方法新增到您的實作中。

public function rollBack();

資料庫交易中的同步任務

影響可能性：非常低

先前，同步任務（使用 sync 佇列驅動程式的任務）會立即執行，無論佇列連線的 after_commit 設定選項是否設定為 true，或是否在任務上調用了 afterCommit 方法。

在 Laravel 11 中，同步佇列任務現在會遵守佇列連線或任務的「after commit」設定。

速率限制

每秒速率限制

影響的可能性：中等

Laravel 11 支援每秒速率限制，而不是被限制為每分鐘粒度。您應該注意與此變更相關的各種潛在的破壞性變更。

GlobalLimit 類別建構子現在接受秒，而不是分鐘。此類別未記錄在文件中，通常不會被您的應用程式使用。

new GlobalLimit($attempts, 2 * 60);

Limit 類別建構子現在接受秒，而不是分鐘。此類別的所有文件記錄用法都限制為靜態建構子，例如 Limit::perMinute 和 Limit::perSecond。然而，如果您要手動實例化此類別，您應該更新您的應用程式以將秒數提供給類別的建構子。

new Limit($key, $attempts, 2 * 60);

Limit 類別的 decayMinutes 屬性已重新命名為 decaySeconds，現在包含秒數而不是分鐘。

Illuminate\Queue\Middleware\ThrottlesExceptions 和 Illuminate\Queue\Middleware\ThrottlesExceptionsWithRedis 類別建構子現在接受秒，而不是分鐘。

new ThrottlesExceptions($attempts, 2 * 60);
new ThrottlesExceptionsWithRedis($attempts, 2 * 60);

Cashier Stripe

更新 Cashier Stripe

影響可能性：高

Laravel 11 不再支援 Cashier Stripe 14.x。因此，您應該將應用程式的 Laravel Cashier Stripe 依賴性更新為 ^15.0 在您的 composer.json 檔案中。

Cashier Stripe 15.0 不再自動從自己的遷移目錄載入遷移檔案。相反地，您應該執行以下命令以將 Cashier Stripe 的遷移檔案發佈到您的應用程式。

php artisan vendor:publish --tag=cashier-migrations

請檢閱完整的 Cashier Stripe 升級指南，以了解其他破壞性變更。

Spark (Stripe)

更新 Spark Stripe

影響可能性：高

Laravel 11 不再支援 Laravel Spark Stripe 4.x。因此，您應該將應用程式的 Laravel Spark Stripe 依賴性更新為 ^5.0 在您的 composer.json 檔案中。

Spark Stripe 5.0 不再自動從自己的遷移目錄載入遷移檔案。相反地，您應該執行以下命令以將 Spark Stripe 的遷移檔案發佈到您的應用程式。

php artisan vendor:publish --tag=spark-migrations

請檢閱完整的 Spark Stripe 升級指南，以了解其他破壞性變更。

Passport

更新 Passport

影響可能性：高

Laravel 11 不再支援 Laravel Passport 11.x。因此，您應該將應用程式的 Laravel Passport 依賴性更新為 ^12.0 在您的 composer.json 檔案中。

Passport 12.0 不再自動從自己的遷移目錄載入遷移檔案。相反地，您應該執行以下命令以將 Passport 的遷移檔案發佈到您的應用程式。

php artisan vendor:publish --tag=passport-migrations

此外，密碼授權類型預設為停用。您可以在應用程式的 AppServiceProvider 的 boot 方法中調用 enablePasswordGrant 方法來啟用它。

public function boot(): void
{
    Passport::enablePasswordGrant();
}

Sanctum

更新 Sanctum

影響可能性：高

Laravel 11 不再支援 Laravel Sanctum 3.x。因此，您應將應用程式的 Laravel Sanctum 相依性更新至 ^4.0 在您的 composer.json 檔案中。

Sanctum 4.0 不再自動從其自身的 migrations 目錄載入遷移檔案。您應執行以下命令，將 Sanctum 的遷移檔案發佈至您的應用程式。

php artisan vendor:publish --tag=sanctum-migrations

接著，在您應用程式的 config/sanctum.php 設定檔中，您應將 authenticate_session、encrypt_cookies 和 validate_csrf_token 中介軟體的參考更新為以下內容。

'middleware' => [
    'authenticate_session' => Laravel\Sanctum\Http\Middleware\AuthenticateSession::class,
    'encrypt_cookies' => Illuminate\Cookie\Middleware\EncryptCookies::class,
    'validate_csrf_token' => Illuminate\Foundation\Http\Middleware\ValidateCsrfToken::class,
],

Telescope

更新 Telescope

影響可能性：高

Laravel 11 不再支援 Laravel Telescope 4.x。因此，您應將應用程式的 Laravel Telescope 相依性更新至 ^5.0 在您的 composer.json 檔案中。

Telescope 5.0 不再自動從其自身的 migrations 目錄載入遷移檔案。您應執行以下命令，將 Telescope 的遷移檔案發佈至您的應用程式。

php artisan vendor:publish --tag=telescope-migrations

Spatie Once 套件

影響的可能性：中等

Laravel 11 現在提供了自己的 once 函式，以確保指定的閉包只執行一次。因此，如果您的應用程式依賴 spatie/once 套件，您應將其從應用程式的 composer.json 檔案中移除，以避免衝突。

雜項

我們也鼓勵您查看 laravel/laravel GitHub 儲存庫中的變更。雖然許多這些變更並非必要，您可能會希望讓這些檔案與您的應用程式同步。其中一些變更將在本升級指南中涵蓋，但其他變更，例如設定檔或註解的變更，則不會涵蓋。您可以使用 GitHub 比較工具輕鬆查看變更，並選擇對您重要的更新。