Documentation Index
Fetch the complete documentation index at: https://kawax.biz/llms.txt
Use this file to discover all available pages before exploring further.
はじめに
Laravel 13 は 2026年3月にリリースされました。このガイドでは Laravel 12.x から 13.x へのアップグレード手順を説明します。アップグレードに必要な推定時間は 約10分 です。ただし、破壊的変更がアプリケーションに与える影響は規模や使用している機能によって異なります。
AIを使ったアップグレード
Laravel Boost を使ってアップグレードを自動化することもできます。Boost はファーストパーティの MCP サーバーで、AI アシスタントに段階的なアップグレードプロンプトを提供します。Laravel 12 アプリケーションにインストール後、Claude Code、Cursor、OpenCode、Gemini、VS Code で/upgrade-laravel-v13 スラッシュコマンドを使用して Laravel 13 へのアップグレードを開始できます。このコマンドには laravel/boost ^2.0 が必要です。
スラッシュコマンドが使えない AI ツールでも、プロンプトファイルを直接参照することで同じアップグレード手順を実行できます。以下のプロンプトをそのまま AI に貼り付けてください。
プロンプト
影響度別の変更点
影響度: 高
- 依存関係の更新
- Laravel インストーラーの更新
- リクエスト偽造防止 (CSRF)
影響度: 中
- キャッシュ
serializable_classes設定 - セッション
serialization設定
影響度: 低
- キャッシュプレフィックスとセッション Cookie 名
- コレクションモデルのシリアライゼーション
Container::callと Nullable クラスデフォルト- ドメインルート登録の優先順位
JobAttemptedイベントの例外ペイロード- Manager
extendコールバックのバインディング - MySQL
DELETEクエリ (JOIN / ORDER BY / LIMIT) - ページネーション Bootstrap ビュー名
- ポリモーフィックピボットテーブル名の生成
QueueBusyイベントのプロパティ名変更Strファクトリのテスト間リセット
アップグレード手順
依存関係の更新
影響度: 高composer.json の以下の依存関係を更新してください。
Laravel インストーラーの更新
影響度: 高 Laravel インストーラー CLI を使って新しい Laravel アプリケーションを作成する場合は、Laravel 13.x 対応のバージョンに更新してください。composer global require でインストールした場合:
破壊的変更 (Breaking Changes)
セキュリティ
リクエスト偽造防止
影響度: 高 Laravel の CSRF ミドルウェアがVerifyCsrfToken から PreventRequestForgery にリネームされました。また、Sec-Fetch-Site ヘッダーを使ったリクエスト発信元の検証が追加されています。
VerifyCsrfToken と ValidateCsrfToken は非推奨のエイリアスとして残っていますが、直接参照している箇所はすべて PreventRequestForgery に更新する必要があります。特にテストやルート定義でミドルウェアを除外している場合は注意が必要です。
preventRequestForgery(...) が使用可能になりました。
キャッシュ
キャッシュプレフィックスとセッション Cookie 名
影響度: 低 Laravel のデフォルトのキャッシュおよび Redis キープレフィックスがハイフン区切りのサフィックスを使用するようになりました。また、デフォルトのセッション Cookie 名がStr::snake(...) を使用するようになりました。
多くのアプリケーションでは設定ファイルで明示的に値を設定しているため、この変更の影響を受けません。フレームワークのフォールバック設定に依存しているアプリケーションのみ影響を受けます。
.env ファイルで明示的に設定してください。
キャッシュ serializable_classes 設定
影響度: 中
デフォルトの cache 設定に serializable_classes オプションが追加され、デフォルトは false になりました。これにより、APP_KEY が漏洩した場合の PHP デシリアライゼーションガジェットチェーン攻撃を防ぎます。
アプリケーションが意図的にキャッシュに PHP オブジェクトを保存している場合、デシリアライズを許可するクラスを明示的にリストアップする必要があります。
セッション serialization 設定
影響度: 中
Laravel 13 のスケルトン (laravel/laravel) の config/session.php に 'serialization' => 'json' が追加されています。ただし、フレームワーク内部のデフォルトは php のままです。
公式のアップグレードガイドにはこの設定の変更が記載されていません。これは 変更しなくてよい という意図だと考えられます。Laravelでは一つ前のバージョンからのアップグレードでは影響がないのでアップグレードガイドに記載されない変更がたまにあります。数年後にアップグレードしようとした時に情報がなくて困るので非公式での記録が大事です。
Laravel 12 までと同じ動作を維持するには、'serialization' => 'php' を明示的に設定してください。
コンテナ
Container::call と Nullable クラスデフォルト
影響度: 低
Container::call が、バインディングが存在しない場合に nullable クラスパラメータのデフォルト値を尊重するようになりました(Laravel 12 でコンストラクタインジェクションに導入された動作と一致します)。
データベース
MySQL DELETE クエリ
影響度: 低
Laravel が MySQL 文法で ORDER BY と LIMIT を含む完全な DELETE ... JOIN クエリをコンパイルするようになりました。
以前のバージョンでは、JOIN を伴う DELETE で ORDER BY / LIMIT 句が無視されることがありました。Laravel 13 ではこれらの句が生成される SQL に含まれます。その結果、この構文をサポートしない一部のデータベースエンジンで QueryException が発生する可能性があります。
Eloquent
ポリモーフィックピボットテーブル名の生成
影響度: 低 カスタムピボットモデルクラスを使用するポリモーフィックピボットモデルのテーブル名が推測される際、Laravel が複数形の名前を生成するようになりました。 以前の単数形の推測名に依存していた場合は、ピボットモデルでテーブル名を明示的に定義してください。コレクションモデルのシリアライゼーション
影響度: 低 Eloquent モデルコレクションがシリアライズおよびリストア(キュー投入されたジョブなど)される際、Eager ロードされたリレーションがモデルのために復元されるようになりました。 デシリアライゼーション後にリレーションが存在しないことに依存していたコードがある場合は、修正が必要です。キュー
JobAttempted イベントの例外ペイロード
影響度: 低
Illuminate\Queue\Events\JobAttempted イベントが、以前の boolean の $exceptionOccurred プロパティに代わって、例外オブジェクト(または null)を $exception で公開するようになりました。
QueueBusy イベントのプロパティ名変更
影響度: 低
Illuminate\Queue\Events\QueueBusy イベントのプロパティ $connection が、他のキューイベントとの一貫性のために $connectionName にリネームされました。
ルーティング
ドメインルート登録の優先順位
影響度: 低 明示的なドメインを持つルートが、ルートマッチングで非ドメインルートよりも優先されるようになりました。 これにより、キャッチオールのサブドメインルートが、非ドメインルートが先に登録されている場合でも一貫して動作するようになります。サポート
Manager extend コールバックのバインディング
影響度: 低
Manager の extend メソッドで登録されたカスタムドライバーのクロージャが、マネージャーインスタンスにバインドされるようになりました。
以前はこれらのコールバック内で別のオブジェクト(サービスプロバイダーインスタンスなど)が $this として参照されていた場合、use (...) で値をクロージャキャプチャに移動する必要があります。
Str ファクトリのテスト間リセット
影響度: 低
Laravel がテストのティアダウン時にカスタム Str ファクトリをリセットするようになりました。
カスタム UUID / ULID / ランダム文字列ファクトリがテストメソッド間で持続することに依存していた場合は、関連する各テストまたはセットアップフックで設定するようにしてください。
ビュー
ページネーション Bootstrap ビュー名
影響度: 低 Bootstrap 3 デフォルトの内部ページネーションビュー名が明示的になりました。非推奨になった機能
| 機能 | 代替手段 |
|---|---|
VerifyCsrfToken ミドルウェア | PreventRequestForgery |
ValidateCsrfToken ミドルウェア | PreventRequestForgery |
JobAttempted::$exceptionOccurred | JobAttempted::$exception |
QueueBusy::$connection | QueueBusy::$connectionName |
コントラクトの追加
影響度: 非常に低 カスタム実装を持つ場合のみ影響があります。Dispatcher コントラクト
Illuminate\Contracts\Bus\Dispatcher コントラクトに dispatchAfterResponse($command, $handler = null) メソッドが追加されました。
ResponseFactory コントラクト
Illuminate\Contracts\Routing\ResponseFactory コントラクトに eventStream シグネチャが追加されました。
MustVerifyEmail コントラクト
Illuminate\Contracts\Auth\MustVerifyEmail コントラクトに markEmailAsUnverified() が追加されました。
Queue コントラクト
Illuminate\Contracts\Queue\Queue コントラクトに以下のキューサイズ検査メソッドが追加されました(以前はドックブロックのみで宣言されていました)。
pendingSizedelayedSizereservedSizecreationTimeOfOldestPendingJob
Store / Repository コントラクト
キャッシュコントラクトに TTL 延長のための touch メソッドが追加されました。
新機能のハイライト
AIアシストアップグレード (Laravel Boost)
Laravel Boost は公式の MCP サーバーです。AI エディターと連携して/upgrade-laravel-v13 コマンドでアップグレードを半自動化できます。
Sec-Fetch-Site ヘッダーによるリクエスト発信元検証
PreventRequestForgery ミドルウェアが Sec-Fetch-Site ヘッダーを使った追加のオリジン検証を行います。これにより CSRF 保護が強化されています。
キャッシュの安全なデシリアライゼーション
serializable_classes 設定により、許可するクラスのみがデシリアライズされるようになりました。PHP デシリアライゼーション攻撃に対するセキュリティが向上しています。
SSE (Server-Sent Events) の eventStream
ResponseFactory コントラクトに eventStream が追加され、Server-Sent Events のサポートが改善されました。
キュー可視性の向上
Queue コントラクトの pendingSize、delayedSize、reservedSize などのメソッドによって、キューの状態をより細かく監視できるようになりました。
よくある移行時の問題と解決策
問題: CSRF 関連のテストが失敗する
症状:VerifyCsrfToken を参照しているテストがクラスが見つからないエラーで失敗する。
解決策: すべての参照を PreventRequestForgery に更新してください。
問題: キャッシュからオブジェクトが復元できない
症状: キャッシュから取得したデータがnull になる、または UnserializationFailedException が発生する。
解決策: config/cache.php で serializable_classes に使用するクラスを追加するか、キャッシュする値を配列に変換してください。
問題: JobAttempted リスナーが機能しない
症状: $event->exceptionOccurred が null や未定義エラーになる。
解決策: $event->exception !== null に変更してください。
問題: セッションが無効化される
症状: アップグレード後にユーザーがログアウトされる。 解決策: デフォルトのセッション Cookie 名が変更されています。.env で SESSION_COOKIE を明示的に設定して以前の値を維持してください。
問題: キャッシュキーが見つからない
症状: アップグレード後にキャッシュミスが増加する。 解決策: キャッシュプレフィックスが変更されています。.env で CACHE_PREFIX を設定するか、キャッシュをクリアしてください。
参考資料
- 公式アップグレードガイド (英語)
- laravel/laravel リポジトリの差分 (12.x → 13.x)
- Laravel Shift — アップグレードを自動化するコミュニティサービス
- Laravel Boost — AI アシストアップグレード用 MCP サーバー