アップグレードガイド

• 10.xから11.0へのアップグレード

影響の大きい変更

影響の大きい中程度の変更

影響の少ない変更

10.xから11.0へのアップグレード

推定アップグレード時間: 15分

依存関係の更新

影響の可能性：高い

PHP 8.2.0が必須

LaravelはPHP 8.2.0以上を必要とするようになりました。

curl 7.34.0が必須

LaravelのHTTPクライアントは、curl 7.34.0以上を必要とするようになりました。

Composerの依存関係

アプリケーションのcomposer.jsonファイルで、次の依存関係を更新する必要があります。

アプリケーションで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

最後に、Laravelはこのパッケージに依存しなくなったため、以前にアプリケーションに追加した場合は、doctrine/dbal Composer依存関係を削除できます。

アプリケーション構造

Laravel 11では、デフォルトのファイルが少ない新しいデフォルトのアプリケーション構造が導入されています。つまり、新しいLaravelアプリケーションには、サービスプロバイダー、ミドルウェア、および構成ファイルが少なくなっています。

ただし、Laravel 11はLaravel 10アプリケーション構造もサポートするように慎重に調整されているため、Laravel 10からLaravel 11にアップグレードするアプリケーションがアプリケーション構造を移行しようとすることを推奨しません。

認証

パスワードの再ハッシュ

影響の可能性：低い

Laravel 11では、パスワードが最後にハッシュされてからハッシュアルゴリズムの「ワークファクター」が更新された場合、認証中にユーザーのパスワードが自動的に再ハッシュされます。

通常、これはアプリケーションを中断しません。ただし、Userモデルの「パスワード」フィールドの名前がpassword以外の場合は、モデルのauthPasswordNameプロパティを介してフィールドの名前を指定する必要があります。

protected $authPasswordName = 'custom_password_field';

または、アプリケーションのconfig/hashing.php構成ファイルにrehash_on_loginオプションを追加して、パスワードの再ハッシュを無効にすることもできます。

'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トレイトに含まれているため、このメソッドを自動的に受け取ります。

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();

アプリケーション内の既存のすべての「変更」マイグレーションを更新してカラムの既存の属性を保持したくない場合は、単にマイグレーションをスカッシュすることができます。

php artisan schema:dump

マイグレーションがスカッシュされると、Laravelは保留中のマイグレーションを実行する前に、アプリケーションのスキーマファイルを使用してデータベースを「マイグレーション」します。

浮動小数点型

影響の可能性：高い

doubleとfloatのマイグレーションカラム型は、すべてのデータベースで一貫性を持つように書き直されました。

doubleカラム型は、標準SQL構文である、合計桁数と小数点以下の桁数（小数点以下の桁数）のないDOUBLE相当のカラムを作成するようになりました。したがって、$totalと$placesの引数を削除できます。

$table->double('amount');

floatカラム型は、合計桁数と小数点以下の桁数（小数点以下の桁数）のないFLOAT相当のカラムを作成するようになりました。ただし、オプションの$precision指定を使用して、ストレージサイズを4バイトの単精度カラムまたは8バイトの倍精度カラムとして決定できます。したがって、$totalと$placesの引数を削除し、必要に応じて、データベースのドキュメントに従って、オプションの$precisionを目的の値に指定できます。

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

unsignedDecimal、unsignedDouble、およびunsignedFloatメソッドは、これらのカラム型のunsigned修飾子がMySQLで非推奨となり、他のデータベースシステムでは標準化されていなかったため、削除されました。ただし、これらのカラム型の非推奨のunsigned属性を引き続き使用したい場合は、カラム定義にunsignedメソッドをチェーンできます。

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

専用のMariaDBドライバ

影響の可能性：非常に低い

MariaDBデータベースに接続する際に常にMySQLドライバを利用する代わりに、Laravel 11ではMariaDB専用のデータベースドライバが追加されました。

アプリケーションがMariaDBデータベースに接続する場合、新しいmariadbドライバに接続構成を更新して、将来のMariaDB固有の機能の恩恵を受けることができます。

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

現在、新しいMariaDBドライバは、1つの例外を除いて、現在のMySQLドライバのように動作します。uuidスキーマビルダーメソッドは、char(36)カラムではなく、ネイティブUUIDカラムを作成します。

既存のマイグレーションで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型を登録する必要もなくなりました。

さらに、アプリケーションの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を使用する場合、新しいスキーマメソッドはいずれも3部構成の参照（例：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);

パッケージ

アプリケーションへのサービスプロバイダの公開

影響の可能性：非常に低い

アプリケーションのapp/Providersディレクトリにサービスプロバイダを手動で公開し、アプリケーションのconfig/app.php構成ファイルを変更してサービスプロバイダを登録するLaravelパッケージを作成した場合は、新しいServiceProvider::addProviderToBootstrapFileメソッドを利用するようにパッケージを更新する必要があります。

addProviderToBootstrapFileメソッドは、新しいLaravel 11アプリケーションではproviders配列がconfig/app.php構成ファイル内に存在しないため、公開したサービスプロバイダをアプリケーションのbootstrap/providers.phpファイルに自動的に追加します。

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

キュー

BatchRepositoryインターフェース

影響の可能性：非常に低い

Illuminate\Bus\BatchRepositoryインターフェースに新しいrollBackメソッドが追加されました。独自のパッケージまたはアプリケーション内でこのインターフェースを実装している場合は、実装にこのメソッドを追加する必要があります。

public function rollBack();

データベーストランザクションでの同期ジョブ

影響の可能性：非常に低い

以前は、同期ジョブ（syncキュードライバを使用するジョブ）は、キュー接続のafter_commit構成オプションがtrueに設定されているか、ジョブでafterCommitメソッドが呼び出されているかに関係なく、すぐに実行されていました。

Laravel 11では、同期キュージョブは、キュー接続またはジョブの「コミット後」構成を尊重するようになりました。

レート制限

秒単位のレート制限

影響の可能性：中程度

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依存関係をcomposer.jsonファイルの^15.0に更新する必要があります。

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依存関係をcomposer.jsonファイルの^5.0に更新する必要があります。

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依存関係をcomposer.jsonファイルの^12.0に更新する必要があります。

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 依存関係を composer.json ファイルで ^4.0 に更新する必要があります。

Sanctum 4.0 は、独自の migrations ディレクトリから migrations を自動的にロードしなくなりました。代わりに、次のコマンドを実行して Sanctum の migrations をアプリケーションに公開する必要があります。

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 依存関係を composer.json ファイルで ^5.0 に更新する必要があります。

Telescope 5.0 は、独自の migrations ディレクトリから migrations を自動的にロードしなくなりました。代わりに、次のコマンドを実行して Telescope の migrations をアプリケーションに公開する必要があります。

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

Spatie Onceパッケージ

影響の可能性：中程度

Laravel 11 は、指定されたクロージャが一度だけ実行されるようにするための独自の once 関数を提供するようになりました。したがって、アプリケーションが spatie/once パッケージに依存している場合は、競合を避けるために、アプリケーションの composer.json ファイルから削除する必要があります。

その他

laravel/laravel GitHub リポジトリの変更も確認することをお勧めします。これらの変更の多くは必須ではありませんが、これらのファイルをアプリケーションと同期させておくとよいでしょう。これらの変更の一部は、このアップグレードガイドで説明しますが、設定ファイルやコメントなどの変更は説明しません。 GitHub 比較ツールを使用して変更を簡単に確認し、どの更新が重要かを選択できます。