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 12 は 2025年2月にリリースされました。このガイドでは Laravel 11.x から 12.x へのアップグレード手順を説明します。アップグレードに必要な推定時間は 約5分 です。ただし、破壊的変更がアプリケーションに与える影響は規模や使用している機能によって異なります。
Laravel Shift を使った自動アップグレード
Laravel Shift を使ってアップグレードを自動化することもできます。Shift はアプリケーションの依存関係や設定ファイルを自動的に更新してくれます。影響度別の変更点
影響度: 高
- 依存関係の更新
- Laravel インストーラーの更新
影響度: 中
- Eloquent
HasUuidsトレイトと UUIDv7
影響度: 低
- Carbon 3
- Concurrency の結果インデックスマッピング
- コンテナのクラス依存解決
- 画像バリデーションの SVG 除外
- ローカルファイルシステムディスクのデフォルトルートパス
- マルチスキーマのデータベースインスペクション
- ネストされた配列リクエストのマージ
アップグレード手順
依存関係の更新
影響度: 高composer.json の以下の依存関係を更新してください。
Laravel インストーラーの更新
影響度: 高 Laravel インストーラー CLI を使って新しい Laravel アプリケーションを作成する場合は、Laravel 12.x および新しいスターターキットに対応したバージョンに更新してください。composer global require でインストールした場合:
php.new でインストールした場合は、OS に合わせて再インストールコマンドを実行してください。
- macOS
- Windows PowerShell
- Linux
新スターターキット
Laravel 12 では、従来の Breeze や Jetstream に代わる新しいスターターキットが導入されました。laravel new を実行すると、フロントエンドスタックを対話的に選択できます。
利用可能なスターターキット:
- React — Inertia 2、React 19、TypeScript、Tailwind 4、shadcn/ui
- Vue — Inertia 2、Vue Composition API、TypeScript、Tailwind 4、shadcn-vue
- Svelte — Inertia 2、Svelte 5、TypeScript、Tailwind 4、shadcn-svelte
- Livewire — Livewire、Tailwind 4、Flux UI
既存のアプリケーションをアップグレードする場合、スターターキットを導入し直す必要はありません。新規プロジェクト向けの変更です。
破壊的変更 (Breaking Changes)
Eloquent
HasUuids トレイトと UUIDv7
影響度: 中
HasUuids トレイトが UUID v7 (順序付き UUID) を返すようになりました。以前の順序付き UUID v4 の動作を維持したい場合は、HasVersion4Uuids トレイトに切り替えてください。
HasVersion7Uuids トレイトを使用していた場合は、HasUuids トレイトに変更してください(同じ動作になりました)。
バリデーション
画像バリデーションの SVG 除外
影響度: 低image バリデーションルールがデフォルトで SVG を許可しなくなりました。SVG を許可する場合は明示的に指定してください。
ストレージ
ローカルファイルシステムディスクのデフォルトルートパス
影響度: 低filesystems 設定で local ディスクを明示的に定義していない場合、デフォルトのルートパスが storage/app から storage/app/private に変更されました。
以前の動作を維持するには、設定ファイルで local ディスクを明示的に定義してください。
データベース
マルチスキーマのデータベースインスペクション
影響度: 低Schema::getTables()、Schema::getViews()、Schema::getTypes() がデフォルトですべてのスキーマの結果を返すようになりました。特定のスキーマのみを対象にするには schema 引数を渡してください。
Schema::getTableListing() がデフォルトでスキーマ修飾されたテーブル名を返すようになりました。
データベースコンストラクターシグネチャの変更
影響度: 非常に低Illuminate\Database\Schema\Blueprint と Illuminate\Database\Grammar のコンストラクターが Connection インスタンスを第一引数として要求するようになりました。
| API | 状態 |
|---|---|
Blueprint::getPrefix() | 非推奨 |
Connection::withTablePrefix() | 削除 |
Grammar::getTablePrefix() / setTablePrefix() | 非推奨 |
Grammar::setConnection() | 削除 |
Concurrency
結果インデックスマッピング
影響度: 低Concurrency::run() に連想配列を渡した場合、結果がそれぞれのキーと対応して返されるようになりました。
コンテナ
クラス依存解決のデフォルト値
影響度: 低 DIコンテナが、クラスインスタンスを解決する際にクラスプロパティのデフォルト値を尊重するようになりました。リクエスト
ネストされた配列リクエストのマージ
影響度: 低$request->mergeIfMissing() でドット記法を使ったネストされた配列データをマージできるようになりました。以前はドット記法のキーがそのまま最上位のキーとして作成されていました。
ルーティング
ルートの優先順位
影響度: 低 同じ名前を持つ複数のルートがある場合の動作が、キャッシュあり・なしで統一されました。キャッシュなしのルーティングでも、最後ではなく最初に登録されたルートが優先されるようになりました。認証
DatabaseTokenRepository コンストラクターの変更
影響度: 非常に低
Illuminate\Auth\Passwords\DatabaseTokenRepository のコンストラクターが $expires パラメーターを分単位ではなく秒単位で受け取るようになりました。
Carbon 3
影響度: 低 Carbon 2.x のサポートが削除されました。Laravel 12 のアプリケーションはすべて Carbon 3.x が必要です。まとめ
Laravel 12 は比較的スムーズにアップグレードできるバージョンです。主な注意点をまとめます。| 変更点 | 影響度 | 対応 |
|---|---|---|
composer.json の依存関係更新 | 高 | laravel/framework ^12.0 に変更 |
| Laravel インストーラーの更新 | 高 | composer global update |
HasUuids → UUIDv7 | 中 | 必要なら HasVersion4Uuids に切り替え |
image バリデーションの SVG 除外 | 低 | SVG を許可する場合は allow_svg を追加 |
| ローカルディスクのデフォルトルート変更 | 低 | 設定ファイルで明示的に指定 |
| Carbon 3 必須 | 低 | API 互換性を確認 |
参考資料
- 公式アップグレードガイド (英語)
- laravel/laravel リポジトリの差分 (11.x → 12.x)
- 新しいスターターキット
- Laravel Shift — アップグレードを自動化するコミュニティサービス
- Carbon 3 移行ガイド