Laravel 13.x アップグレードガイド

影響度の高い変更High Impact Changes

影響度が中程度の変更Medium Impact Changes

影響度の低い変更Low Impact Changes

12.xから13.0へのアップグレードUpgrading To 13.0 From 12.x

推定アップグレード時間：10分Estimated Upgrade Time: 10 Minutes

note Note: 私たちは、考えられるすべての破壊的変更をドキュメント化するよう努めています。これらの破壊的変更の中には、フレームワークの目立たない部分にあるものもあるため、実際にアプリケーションに影響を与えるのはこれらの変更の一部のみである可能性があります。時間を節約するために、Shiftを利用することもできます。ShiftはLaravelのアップグレードを自動化する、コミュニティによってメンテナンスされているサービスです。[!NOTE] We attempt to document every possible breaking change. Since some of these breaking changes are in obscure parts of the framework only a portion of these changes may actually affect your application. To save time, you may use Shift[https://laravelshift.com]. Shift is a community-maintained service that automates Laravel upgrades.

AIを使用したアップグレードUpgrading Using AI

Laravel Boostを使用して、アップグレードを自動化できます。BoostはファーストパーティのMCPサーバであり、AIアシスタントにガイド付きのアップグレードプロンプトを提供します。Laravel 12アプリケーションにインストールしたら、Claude Code、Cursor、OpenCode、Gemini、またはVS Codeで/upgrade-laravel-13スラッシュコマンドを使用して、Laravel 13へのアップグレードを開始してください。You can automate your upgrade using Laravel Boost[https://github.com/laravel/boost]. Boost is a first-party MCP server that provides your AI assistant with guided upgrade prompts — once installed in any Laravel 12 application, use the /upgrade-laravel-13 slash command in Claude Code, Cursor, OpenCode, Gemini. or VS Code to begin the upgrade to Laravel 13.

依存パッケージのアップデートUpdating Dependencies

影響の可能性： 高いLikelihood Of Impact: High

アプリケーションのcomposer.jsonファイルにある、以下の依存パッケージを更新してください。You should update the following dependencies in your application's composer.json file:

LaravelインストーラのアップデートUpdating the Laravel Installer

新しいLaravelアプリケーションを作成するためにLaravelインストーラCLIツールを使用している場合は、Laravel 13.xとの互換性のためにインストーラのインストールをアップデートしてください。If you are using the Laravel installer CLI tool to create new Laravel applications, you should update your installer installation for Laravel 13.x compatibility.

composer global require経由でLaravelインストーラをインストールした場合は、composer global updateを使用してインストーラをアップデートできます。If you installed the Laravel installer via composer global require, you may update the installer using composer global update:

composer global update laravel/installer

または、Laravel HerdバンドルのLaravelインストーラを使用している場合は、Herdインストールを最新リリースへ更新してください。Or, if you are using Laravel Herd's[https://herd.laravel.com] bundled copy of the Laravel installer, you should update your Herd installation to the latest release.

キャッシュCache

キャッシュプレフィックスとセッションクッキー名Cache Prefixes and Session Cookie Names

影響の可能性： 低いLikelihood Of Impact: Low

LaravelのデフォルトのキャッシュとRedisキーのプレフィックスは、ハイフンでつながれたサフィックスを使用するようになりました。さらに、デフォルトのセッションクッキー名は、アプリケーション名にStr::snake(...)を使用するようになりました。Laravel's default cache and Redis key prefixes now use hyphenated suffixes. In addition, the default session cookie name now uses Str::snake(...) for the application name.

ほとんどのアプリケーションでは、アプリケーションレベルの設定ファイルで既にこれらの値を定義しているため、この変更は適用されません。これは主に、対応するアプリケーション設定値が存在しない場合にフレームワークレベルのフォールバック設定に依存しているアプリケーションに影響します。In most applications, this change will not apply because application-level configuration files already define these values. This primarily affects applications that rely on framework-level fallback configuration when corresponding application config values are not present.

アプリケーションがこれらの生成されたデフォルト値に依存している場合、アップグレード後にキャッシュキーとセッションクッキー名が変わる可能性があります。If your application relies on these generated defaults, cache keys and session cookie names may change after upgrading:

// Laravel <= 12.x
Str::slug((string) env('APP_NAME', 'laravel'), '_').'_cache_';
Str::slug((string) env('APP_NAME', 'laravel'), '_').'_database_';
Str::slug((string) env('APP_NAME', 'laravel'), '_').'_session';

// Laravel >= 13.x
Str::slug((string) env('APP_NAME', 'laravel')).'-cache-';
Str::slug((string) env('APP_NAME', 'laravel')).'-database-';
Str::snake((string) env('APP_NAME', 'laravel')).'_session';

以前の挙動を維持するには、環境変数でCACHE_PREFIX、REDIS_PREFIX、SESSION_COOKIEを明示的に設定してください。To retain previous behavior, explicitly configure CACHE_PREFIX, REDIS_PREFIX, and SESSION_COOKIE in your environment.

StoreおよびRepository契約：touchStore and Repository Contracts: touch

影響の可能性： とても低いLikelihood Of Impact: Very Low

キャッシュ契約に、アイテムのTTLを延長するためのtouchメソッドを含めました。カスタムキャッシュストアの実装をメンテナンスしている場合は、このメソッドを追加してください。The cache contracts now include a touch method for extending item TTLs. If you maintain custom cache store implementations, you should add this method:

// Illuminate\Contracts\Cache\Store
public function touch($key, $seconds);

キャッシュのserializable_classes設定Cache serializable_classes Configuration

影響の可能性：　中程度Likelihood Of Impact: Medium

デフォルトのアプリケーションcache設定へ、falseに設定したserializable_classesオプションを含めました。これにより、アプリケーションのAPP_KEYが漏洩した場合のPHPデシリアライゼーションガジェットチェーン攻撃を防ぐために、キャッシュのアンシリアライズ挙動が強化しました。アプリケーションが意図的にPHPオブジェクトをキャッシュに保存している場合は、アンシリアライズを許可するクラスを明示的にリストする必要があります。The default application cache configuration now includes a serializable_classes option set to false. This hardens cache unserialization behavior to help prevent PHP deserialization gadget chain attacks if your application's APP_KEY is leaked. If your application intentionally stores PHP objects in cache, you should explicitly list the classes that may be unserialized:

'serializable_classes' => [
    App\Data\CachedDashboardStats::class,
    App\Support\CachedPricingSnapshot::class,
],

アプリケーションが以前、任意のキャッシュ済みオブジェクトのアンシリアライズに依存していた場合は、その使用方法を明示的なクラスの許可リストまたは非オブジェクトのキャッシュペイロード（配列など）に移行する必要があります。If your application previously relied on unserializing arbitrary cached objects, you will need to migrate that usage to explicit class allow-lists or to non-object cache payloads (such as arrays).

コンテナContainer

Container::callとNullableクラスのデフォルト値Container::call and Nullable Class Defaults

影響の可能性： 低いLikelihood Of Impact: Low

Container::callは、バインディングが存在しない場合にNullableなクラスパラメータのデフォルト値を尊重するようになりました。これはLaravel12で導入されたコンストラクタ注入の挙動と一致します。Container::call now respects nullable class parameter defaults when no binding exists, matching constructor injection behavior introduced in Laravel 12:

$container->call(function (?Carbon $date = null) {
    return $date;
});

// Laravel <= 12.x: Carbonインスタンス
// Laravel >= 13.x: null

メソッド呼び出し依存注入のロジックが、以前の挙動に依存していた場合は、アップデートが必要になる可能性があります。If your method-call injection logic depended on the previous behavior, you may need to update it.

契約Contracts

Dispatcher契約：dispatchAfterResponseDispatcher Contract: dispatchAfterResponse

影響の可能性： とても低いLikelihood Of Impact: Very Low

Illuminate\Contracts\Bus\Dispatcher契約へ、dispatchAfterResponse($command, $handler = null)メソッドを含めました。The Illuminate\Contracts\Bus\Dispatcher contract now includes the dispatchAfterResponse($command, $handler = null) method.

カスタムディスパッチャの実装をメンテナンスしている場合は、このメソッドをクラスへ追加してください。If you maintain a custom dispatcher implementation, add this method to your class.

ResponseFactory契約：eventStreamResponseFactory Contract: eventStream

影響の可能性： とても低いLikelihood Of Impact: Very Low

Illuminate\Contracts\Routing\ResponseFactory契約へ、eventStreamシグネチャを含めました。。The Illuminate\Contracts\Routing\ResponseFactory contract now includes an eventStream signature.

この契約のカスタム実装をメンテナンスしている場合は、このメソッドを追加してください。If you maintain a custom implementation of this contract, you should add this method.

MustVerifyEmail契約：markEmailAsUnverifiedMustVerifyEmail Contract: markEmailAsUnverified

影響の可能性： とても低いLikelihood Of Impact: Very Low

Illuminate\Contracts\Auth\MustVerifyEmail契約へ、markEmailAsUnverified()を含めました。The Illuminate\Contracts\Auth\MustVerifyEmail contract now includes markEmailAsUnverified().

この契約のカスタム実装を提供している場合は、互換性を維持するためにこのメソッドを追加してください。If you provide a custom implementation of this contract, add this method to remain compatible.

データベースDatabase

JOIN、ORDER BY、LIMITを伴うMySQLのDELETEクエリMySQL DELETE Queries With JOIN, ORDER BY, and LIMIT

影響の可能性： 低いLikelihood Of Impact: Low

Laravelは、MySQL文法においてORDER BYとLIMITを含む完全なDELETE ... JOINクエリをコンパイルするようにしました。Laravel now compiles full DELETE ... JOIN queries including ORDER BY and LIMIT for MySQL grammar.

以前のバージョンでは、結合した削除においてORDER BY／LIMIT句が黙って無視されることがありました。Laravel13では、これらの句を生成するSQLへ含めます。その結果、この構文をサポートしていないデータベースエンジン（標準的なMySQL／MariaDBバリアントなど）は、制限のない削除を実行する代わりにQueryExceptionを投げる可能性があります。In previous versions, ORDER BY / LIMIT clauses could be silently ignored on joined deletes. In Laravel 13, these clauses are included in the generated SQL. As a result, database engines that do not support this syntax (such as standard MySQL / MariaDB variants) may now throw a QueryException instead of executing an unbounded delete.

EloquentEloquent

モデルの初期起動とネストしたインスタンス化Model Booting and Nested Instantiation

影響の可能性： とても低いLikelihood Of Impact: Very Low

モデルがまだブートしている間にそのモデルの新しいインスタンスを作成することを許可しなくなり、LogicExceptionを投げるようになりました。Creating a new model instance while that model is still booting is now disallowed and throws a LogicException.

これは、モデルのbootメソッドまたはトレイトのboot*メソッド内からモデルをインスタンス化するコードに影響します。This affects code that instantiates models from inside model boot methods or trait boot* methods:

protected static function boot()
{
    parent::boot();

    // ブート中のインスタンス化は許可されなくなりました
    (new static())->getTable();
}

ネストしたブートを避けるために、このロジックをブートサイクルの外に移動してください。Move this logic outside the boot cycle to avoid nested booting.

ポリモーフィックなピボットテーブル名の生成Polymorphic Pivot Table Name Generation

影響の可能性： 低いLikelihood Of Impact: Low

カスタムピボットモデルクラスを使用してポリモーフィックなピボットモデルのテーブル名が推測される場合、Laravelは複数形の名前を生成するようにしました。When table names are inferred for polymorphic pivot models using custom pivot model classes, Laravel now generates pluralized names.

アプリケーションが、モーフピボットテーブルに対して以前の単数形の推測名に依存しており、かつカスタムピボットクラスを使用していた場合は、ピボットモデルでテーブル名を明示的に定義する必要があります。If your application depended on the previous singular inferred names for morph pivot tables and used custom pivot classes, you should explicitly define the table name on your pivot model.

コレクションモデルのシリアライゼーションによるEagerロード済みリレーションの復元Collection Model Serialization Restores Eager-Loaded Relations

影響の可能性： 低いLikelihood Of Impact: Low

Eloquentモデルコレクションがシリアライズおよび復元する際（ジョブのキュー投入時など）、コレクションのモデルに対してEagerロード済みリレーションも復元するようになりました。When Eloquent model collections are serialized and restored (such as in queued jobs), eager-loaded relations are now restored for the collection's models.

デシリアライズ後にリレーションが存在しないことに依存しているコードがある場合は、そのロジックを調整する必要があるかもしれません。If your code depended on relations not being present after deserialization, you may need to adjust that logic.

HTTPクライアントHTTP Client

HTTPクライアントのResponse::throwとthrowifシグネチャHTTP Client Response::throw and throwIf Signatures

影響の可能性： とても低いLikelihood Of Impact: Very Low

HTTPクライアントのレスポンスメソッドは、メソッドシグネチャでコールバックパラメータを宣言するようにしました。The HTTP client response methods now declare their callback parameters in the method signatures:

public function throw($callback = null);
public function throwIf($condition, $callback = null);

カスタムレスポンスクラスでこれらのメソッドをオーバーライドしている場合は、メソッドシグネチャに互換性があることを確認してください。If you override these methods in custom response classes, ensure your method signatures are compatible.

通知Notifications

デフォルトのパスワードリセットの件名Default Password Reset Subject

影響の可能性： とても低いLikelihood Of Impact: Very Low

Laravelのデフォルトのパスワードリセットメールの件名を変更しました。Laravel's default password reset mail subject has changed:

// Laravel <= 12.x
Reset Password Notification

// Laravel >= 13.x
Reset your password

テスト、アサーション、または翻訳のオーバーライドが以前のデフォルト文字列に依存している場合は、それに応じてアップデートしてください。If your tests, assertions, or translation overrides depend on the previous default string, update them accordingly.

キュー投入した通知と見つからないモデルQueued Notifications and Missing Models

影響の可能性： とても低いLikelihood Of Impact: Very Low

キュー投入済み通知は、通知クラスで定義された#[DeleteWhenMissingModels]属性および$deleteWhenMissingModelsプロパティを尊重するようになりました。Queued notifications now respect the #[DeleteWhenMissingModels] attribute and $deleteWhenMissingModels property defined on the notification class.

以前のバージョンでは、削除されることを期待していたケースでも、モデルが見つからないことによってキュー投入された通知ジョブが失敗することがありました。In previous versions, missing models could still cause queued notification jobs to fail in cases where you expected them to be deleted.

キューQueue

``JobAttempted`イベントのエクセプションペイロードJobAttempted Event Exception Payload

影響の可能性： 低いLikelihood Of Impact: Low

Illuminate\Queue\Events\JobAttemptedイベントは、以前のブール値の$exceptionOccurredプロパティに代わり、$exceptionを介してエクセプションオブジェクト（またはnull）を提供するようになりました。The Illuminate\Queue\Events\JobAttempted event now exposes the exception object (or null) via $exception, replacing the previous boolean $exceptionOccurred property:

// Laravel <= 12.x
$event->exceptionOccurred;

// Laravel >= 13.x
$event->exception;

このイベントをリッスンしている場合は、それに応じてリスナのコードをアップデートしてください。If you listen for this event, update your listener code accordingly.

QueueBusyイベントのプロパティ名の変更QueueBusy Event Property Rename

影響の可能性： 低いLikelihood Of Impact: Low

他のキューイベントとの一貫性を保つため、Illuminate\Queue\Events\QueueBusyイベントのプロパティ$connectionを$connectionNameに名称変更しました。The Illuminate\Queue\Events\QueueBusy event property $connection has been renamed to $connectionName for consistency with other queue events.

リスナが$connectionを参照している場合は、$connectionNameにアップデートしてください。If your listeners reference $connection, update them to $connectionName.

Queue契約へのメソッド追加Queue Contract Method Additions

影響の可能性： とても低いLikelihood Of Impact: Very Low

Illuminate\Contracts\Queue\Queue契約に、以前はdocblockでのみ宣言されていたキューサイズ検査メソッドを含めるようになりました。The Illuminate\Contracts\Queue\Queue contract now includes queue size inspection methods that were previously only declared in docblocks.

この契約のカスタムキュードライバ実装をメンテナンスしている場合は、以下の実装を追加してください。If you maintain custom queue driver implementations of this contract, add implementations for:

ルーティングRouting

ドメインルート登録の優先順位Domain Route Registration Precedence

影響の可能性： 低いLikelihood Of Impact: Low

ルートマッチングにおいて、明示的なドメインを持つルートが非ドメインルートよりも優先されるようになりました。Routes with an explicit domain are now prioritized before non-domain routes in route matching.

これにより、非ドメインルートが先に登録されている場合でも、キャッチオールなサブドメインルートが安定して動作するようになります。アプリケーションがドメインルートと非ドメインルートの間の以前の登録優先順位に依存していた場合は、ルートマッチングの挙動を確認してください。This allows catch-all subdomain routes to behave consistently even when non-domain routes are registered earlier. If your application relied on previous registration precedence between domain and non-domain routes, review route matching behavior.

タスクスケジュールScheduling

withSchedulingの登録タイミングwithScheduling Registration Timing

影響の可能性： とても低いLikelihood Of Impact: Very Low

ApplicationBuilder::withScheduling()を介して登録されたスケジュールは、Scheduleが依存解決されるまで延期するようにしました。Schedules registered via ApplicationBuilder::withScheduling() are now deferred until Schedule is resolved.

アプリケーションが初期起動中の即時スケジュール登録タイミングに依存していた場合は、そのロジックを調整する必要があるかもしれません。If your application relied on immediate schedule registration timing during bootstrap, you may need to adjust that logic.

セキュリティSecurity

リクエストフォージェリ保護Request Forgery Protection

影響の可能性： 高いLikelihood Of Impact: High

LaravelのCSRFミドルウェアはVerifyCsrfTokenからPreventRequestForgeryへ名称変更し、Sec-Fetch-Siteヘッダを使用したリクエストオリジンの検証を含むようになりました。Laravel's CSRF middleware has been renamed from VerifyCsrfToken to PreventRequestForgery, and now includes request-origin verification using the Sec-Fetch-Site header.

VerifyCsrfTokenとValidateCsrfTokenは非推奨のエイリアスとして残りますが、特にテストやルート定義でミドルウェアを除外する場合は、直接の参照をPreventRequestForgeryにアップデートする必要があります。VerifyCsrfToken and ValidateCsrfToken remain as deprecated aliases, but direct references should be updated to PreventRequestForgery, especially when excluding middleware in tests or route definitions:

use Illuminate\Foundation\Http\Middleware\PreventRequestForgery;
use Illuminate\Foundation\Http\Middleware\VerifyCsrfToken;

// Laravel <= 12.x
->withoutMiddleware([VerifyCsrfToken::class]);

// Laravel >= 13.x
->withoutMiddleware([PreventRequestForgery::class]);

ミドルウェア設定APIでも、preventRequestForgery(...)を提供するようにしました。The middleware configuration API now also provides preventRequestForgery(...).

サポートSupport

マネージャのextendコールバックの結合Manager extend Callback Binding

影響の可能性： 低いLikelihood Of Impact: Low

マネージャのextendメソッドを介して登録したカスタムドライバのクロージャは、マネージャインスタンスへ結合するようになりました。Custom driver closures registered via manager extend methods are now bound to the manager instance.

以前、これらのコールバック内で別のバインド済みオブジェクト（サービスプロバイダインスタンスなど）を$thisとして依存していた場合は、use (...)を使用してそれらの値をクロージャに取り込むように移動する必要があります。If you previously relied on another bound object (such as a service provider instance) as $this inside these callbacks, you should move those values into closure captures using use (...).

テスト間でのStrファクトリのリセットStr Factories Reset Between Tests

影響の可能性： 低いLikelihood Of Impact: Low

Laravelは、テストのティアダウン中にカスタムStrファクトリをリセットするようにしました。Laravel now resets custom Str factories during test teardown.

テストが、テストメソッド間で持続するカスタムUUID／ULID／ランダム文字列ファクトリに依存していた場合は、各関連テストまたはセットアップフックでそれらを設定する必要があります。If your tests depended on custom UUID / ULID / random string factories persisting between test methods, you should set them in each relevant test or setup hook.

Js::fromはデフォルトでエスケープされていないUnicodeを使用するJs::from Uses Unescaped Unicode By Default

影響の可能性： とても低いLikelihood Of Impact: Very Low

Illuminate\Support\Js::fromは、デフォルトでJSON_UNESCAPED_UNICODEを使用するようになりました。Illuminate\Support\Js::from now uses JSON_UNESCAPED_UNICODE by default.

テストやフロントエンドの出力比較がエスケープ済みのUnicodeシーケンス（例：\u00e8）に依存している場合は、期待値をアップデートしてください。If your tests or frontend output comparisons depended on escaped Unicode sequences (for example \u00e8), update your expectations.

ビューViews

ペジネーションのBootstrapビュー名Pagination Bootstrap View Names

影響の可能性： 低いLikelihood Of Impact: Low

Bootstrap3のデフォルトの内部ペジネーションビュー名を明示的にしました。The internal pagination view names for Bootstrap 3 defaults are now explicit:

// Laravel <= 12.x
pagination::default
pagination::simple-default

// Laravel >= 13.x
pagination::bootstrap-3
pagination::simple-bootstrap-3

アプリケーションが古いペジネーションビュー名を直接参照している場合は、それらの参照をアップデートしてください。If your application references the old pagination view names directly, update those references.

その他Miscellaneous

laravel/laravelのGitHubリポジトリで変更点を確認することもお勧めします。これらの変更の多くは必須ではありませんが、これらのファイルをアプリケーションと同期させておきたいと思うかもしれません。これらの変更の一部はこのアップグレードガイドでカバーされていますが、設定ファイルやコメントの変更など、その他の変更はカバーされていません。GitHubの比較ツールを使用して簡単に変更を確認し、自分にとって重要なアップデートを選択できます。We also encourage you to view the changes in the laravel/laravel GitHub repository[https://github.com/laravel/laravel]. While many of these changes are not required, you may wish to keep these files in sync with your application. Some of these changes will be covered in this upgrade guide, but others, such as changes to configuration files or comments, will not be. You can easily view the changes with the GitHub comparison tool[https://github.com/laravel/laravel/compare/12.x...13.x] and choose which updates are important to you.