Laravel 11から12アップグレード：公式ドキュメントにない変更点の調査

# はじめに
タイトルの件、調査めんどくせぇなぁと思って手を出せてなかったので、生成AI（Genspark）に調査してもらいました。
以下、せっかくなので共有します。（未検証なので取り扱いには注意してください）

調べてもらった結果だけ見ると、11の時にあったような大きな変更は入っていないようですね。
ちなみに、もりもり調査してる様子は見ていて気持ちがいいです。

## Laravel 11から12へのアップグレードの概要

アップグレード作業の背景として、Laravel側での以下のような変更が行われています。

- **PHPバージョン要件**  
Laravel 11および12は、いずれもPHP 8.2以降のバージョンに最適化されており、composer.json内での依存パッケージ（特にsymfonyコンポーネント）の微調整も行われています（参考：Zend by Perforce[1](https://www.zend.com/blog/laravel-php-requirements)）。
- **リリースタイミングとサポート期間**  
リリース日やバグフィックス、セキュリティパッチの提供期間などは、公式リリースノートで大まかな概要が示されているものの、内部実装の変更については詳細な情報が公開されていません（参考：Laravel 12.x Releases[2](https://laravel.com/docs/12.x/releases)）。

---

## 公式ドキュメントに記載されていない変更点の詳細

公式ドキュメントやCHANGELOGには明示されていない非公式な変更も、GitHubのコミット履歴やディスカッション、コミュニティでの議論から明らかになっています。以下では主な変更点について詳しく説明します。

### src/Illuminateディレクトリの実装変更

- **変更内容の概要**  
Laravel 12では、特に設定のロード・マージ処理に関わる部分で大きな変更が見受けられます。  
具体的には、**\\Illuminate\\Foundation\\Bootstrap\\LoadConfiguration** クラスにおける設定ファイルのマージロジックが全面的に見直され、従来の統合処理から変更されています。  
この変更により、全ユーザーが基本設定のマージ処理に影響を受ける可能性があり、現時点では公式ドキュメントに明記されていません。  
※詳細はGitHubディスカッション Laravel Framework Discussion #50876[3](https://github.com/laravel/framework/discussions/50876) を参照。

### configディレクトリのデフォルト設定ファイルの非公式変更

- **認証・セッション設定**  
Laravel 12では、config/auth.phpやconfig/session.phpなどの設定ファイルに対し、各種初期値やマージ方法の変更が実施されています。  
具体例として、認証設定のプロバイダーやガード設定の初期値の調整、セッション管理におけるデフォルトドライバーの更新などが挙げられます。  
※これらの変更は公式CHANGELOGには記載されておらず、GitHub上のコミット差分からのみ確認できる状況です（例：Laravel Framework Discussion #50876[3](https://github.com/laravel/framework/discussions/50876)）。

### composer.jsonの依存関係調整

- \**symfony/コンポーネントのバージョン更新*  
Laravel 12のcomposer.jsonでは、特にsymfony関連の依存関係の微調整が行われています。  
この更新は、フレームワーク内部の処理効率や依存パッケージとの整合性を改善するためのものであり、公式文書上には明文化されていません。  
※GitHubのコミット差分を精査する必要があります。

### framework/src/Illuminate/Foundation/Application.phpの初期化処理

- **初期化プロセスの最適化**  
Laravel 12では、Application.php内の初期化処理に関して、エラーハンドリングや依存関係の解決におけるロジックの再構築が示唆されています。  
※具体的なコードレベルの変更はGitHubのコミット履歴に記録されているため、運用環境での検証が推奨されます（参照：Application.php変更点[4](https://github.com/laravel/framework/commits)）。

### その他の非公式な微調整

- **config/session.phpのドライバー設定**  
セッション管理に関する初期値やデフォルトドライバーの更新も行われており、これらはセッションの安全性やパフォーマンスに直結する変更です。
- **PHPバージョン要件の微調整**  
composer.jsonのPHPバージョン要件に関しては、大幅な変更はないものの、依存パッケージとの整合性のため微調整が実施され、これも公式には明記されていません。

---

## 主要コミュニティ・技術ブログの分析結果

技術ブログやフォーラム、主要パッケージ開発者のアップグレードレポートは、公式ドキュメントに記載されない変更点や障害事例に関して多くの有用な情報を提供しています。以下はその主な内容です。

### laracastsフォーラム

- アップグレード時に、**LoadConfigurationクラスの変更**が原因でconfig/auth.phpなどで予期せぬエラーが発生している事例が複数報告されています。  
※具体例：Laravel Framework Discussion #50876[3](https://github.com/laravel/framework/discussions/50876)

### Redditのr/laravel

- composer.json内のsymfony依存関係のバージョン調整や、内部ロジックの変更に起因する非公式な仕様変更が指摘され、互換性の問題が共有されています。

### Laravel News

- Laravel 12アップグレードに伴う**アプリケーション構造の簡略化**、サービスプロバイダやミドルウェア設定の一元管理、不要ファイルの削減など、隠れた改善点について詳説されています。  
※詳細：Configuring Middleware in Laravel[5](https://laravel-news.com/configuring-middleware-in-laravel)

### Spatie / Beyond Code

- 主要パッケージ開発者によるアップグレードガイドでは、composer.json内の依存関係更新、PHPバージョン要件の調整、各種API変更などが詳細にレポートされ、アップグレード時の注意点や具体的な対応策が示されています。  
※例：Spatie Laravel Permission Upgrading[6](https://spatie.be/docs/laravel-permission/v6/upgrading)

---

## 実稼働環境でのエラーと解決事例

実運用環境における具体的なエラーログや障害レポートもまた、アップグレードの影響を評価する上で重要な情報源です。

### 認証エラー：Userモデルの不一致

- **エラーメッセージ事例**  
『Class App\\Models\\User not found』というエラーが報告されています。
- **原因と解決策**  
config/auth.php内のusersプロバイダー設定において、正しいUserモデルの名前空間（例：App\\Models\\User::class）を指定することが必要です。  
例：

```
'providers' => [
    'users' => [
       'driver' => 'eloquent',
       'model' => App\Models\User::class,
    ],
],
```

※参考：Laravel Authentication Documentation[7](https://laravel.com/docs/12.x/authentication), GitHub Discussion #50876[3](https://github.com/laravel/framework/discussions/50876)

### Vite移行によるビルド失敗

- **変更点**  
Laravel 12では従来のwebpack.mix.jsから、Vite用のvite.config.jsへ移行するため、ビルド設定が大幅に簡略化されています。
- **影響**  
従来のプラグイン登録やエントリーポイント設定が不要となり、代わりにVite固有の高速リロードやモジュール解析機能が標準で組み込まれるため、設定ファイルの記述方法が変更されます。  
※詳細：Laravel 12 Vite Documentation[8](https://laravel.com/docs/12.x/vite)

### ルートキャッシュ最適化不足によるAPI遅延

- **ベンチマーク事例**  
最適化が十分な場合はおおよそ**50 req/sec**、最適化不足の場合は約20%低下し**40 req/sec**程度になるとの概算が示唆されています（ただし、各環境依存）。  
※参考：laracasts.comのベンチマーク事例[9](https://laracasts.com/)

### その他のエラー事例

- **データベースセッションエラー**  
config/session.phpの変更が原因で『database connection failed』や『session store not found』というエラーが発生するケースが報告されています。  
解決には、設定ファイルとデータベース接続設定の再確認が必要です。
- **Symfony Processコンポーネントのバージョン競合**  
composer.json内での依存関係を明示的に指定することで競合を解消する必要があります。  
例：

```
"require": {
    "php": "^8.2",
    "symfony/process": "^5.3",
    ...
}
```

※参考：GitHubのコミット履歴[4](https://github.com/laravel/framework/commits)
- **LoadConfigurationクラス変更による設定マージエラー**  
設定ファイル内の重複キーや不整合な定義を洗い出し、カスタムロジックによる上書き対応が推奨されます。  
※詳細はLaravel Framework Discussion #50876[3](https://github.com/laravel/framework/discussions/50876)を参照。

---

## 結論と推奨事項

Laravel 11から12へのアップグレードは、公式ドキュメントやCHANGELOGに記載されていない実装変更や依存関係の微調整が多数含まれているため、次の点を推奨します。

- **コミット差分の精査**  
GitHubのコミット履歴やディスカッションをもとに、LoadConfigurationクラスや初期設定の変更内容を事前に確認し、各自のシステムへの影響を評価することが重要です。
- **設定ファイルの再確認**  
config/auth.php、config/session.phpなど主要設定ファイルの初期値やマージロジックの変更に注意し、必要に応じてカスタマイズを再検討してください。
- **依存関係の明示的調整**  
composer.jsonでのsymfony/\*依存関係やPHPバージョン要件の微調整に注視し、バージョン競合が発生しないよう明示的な指定を行うことが望ましいです。
- **運用環境でのベンチマーク実施**  
ルートキャッシュや初期化プロセスの変更がパフォーマンスに与える影響を測定し、適切な最適化を実施してください。
- **コミュニティの議論を参考にする**  
laracasts、Reddit、Laravel News、Spatieなどのコミュニティや大手パッケージ開発者のレポートは、有用な情報源ですので、アップグレード前後のフォーラムディスカッションやブログ記事を参考にすることをお勧めします。

---

## 参考文献

- Laravel Framework Discussion #50876[3](https://github.com/laravel/framework/discussions/50876)
- Laravel 12.x Releases – The PHP Framework For Web Artisans[2](https://laravel.com/docs/12.x/releases)
- Laravel Authentication Documentation[7](https://laravel.com/docs/12.x/authentication)
- Laravel 12 Vite Documentation[8](https://laravel.com/docs/12.x/vite)
- Zend by Perforce – Laravel PHP Requirements[1](https://www.zend.com/blog/laravel-php-requirements)
- Configuring Middleware in Laravel – Laravel News[5](https://laravel-news.com/configuring-middleware-in-laravel)
- Spatie Laravel Permission Upgrading[6](https://spatie.be/docs/laravel-permission/v6/upgrading)

本稿がLaravel 11から12へのアップグレードに際して、公式に明記されていない変更点や、現場での具体的な問題点とその対応策を把握する一助となれば幸いです。

---

## まとめ

- Laravel 12では、特に設定のロード・マージ処理に関わる部分で大きな変更が見受けられます。具体的には、**\\Illuminate\\Foundation\\Bootstrap\\LoadConfiguration** クラスにおける設定ファイルのマージロジックが全面的に見直されています。
- Laravel 12では、config/auth.phpやconfig/session.phpなどの設定ファイルに対し、各種初期値やマージ方法の変更が実施されており、公式CHANGELOGには記載されていません。
- Laravel 12のcomposer.jsonでは、特に\*\*symfony/\*\*関連の依存関係の微調整が行われており、フレームワーク内部の処理効率や依存パッケージとの整合性が改善されています。
- Laravel 12では、Application.php内の初期化処理に関してエラーハンドリングや依存関係の解決ロジックの再構築が示唆され、運用環境での動作確認が推奨されています。
- Laravel 12では、従来のwebpack.mix.jsから、**Vite用のvite.config.js**へ移行するため、ビルド設定が大幅に簡略化され、Vite固有の高速リロードやモジュール解析機能が標準で組み込まれています。
- 実運用環境では、『Class App\\Models\\User not found』などのエラーメッセージが報告される事例があり、設定ファイルの再確認やカスタムロジックによる上書き対応が推奨されています。