今回は、2つの案件で Laravel 8 → 12 のバージョンアップ対応を行いました。
その際に発生したエラーや、対応中につまずいたポイントを事例としてまとめています。
対応概要
| サイト① | サイト② | |
|---|---|---|
| OS | － | RHEL 8.8 → RHEL 8.10 |
| PHP | 7.4.33 → 8.4系 | 8.1.11 → 8.4系 |
| MariaDB | 10.5.28（MySQL 5.7系） | － |
| WordPress | 5.2.9 → 6.8 | － |
| Laravel | 8.45.1 → 12系 | 8.83.25 → 12系 |
バージョンアップの進め方
Laravelは一気に最新版へ上げるのではなく、段階的にアップデートを行いました。
各アップデートの手順は、公式のアップグレードガイドを確認しながら進めました。
公式アップグレードガイド
1つバージョンをアップグレードするたびに、以下のコマンドを実行し状態を確認しています。
1 2 | composer update php artisan --version |
1つずつ確認しながら進めることで、問題発生箇所の切り分けがしやすくなります。
サイト①で対応したこと
Laravel 8 → 9：Mailer変更による setReturnPath エラー
Laravel 8 から Laravel 9 にバージョンアップした後、フォーム送信した際に「setReturnPath」にエラーが出て送信できなくなりました。
1 | Call to undefined method Symfony\Component\Mime\Email::setReturnPath() |
Laravel 9 から、メール送信ライブラリが「SwiftMailer」から「Symfony Mailer」に変更されています。
アップグレードガイドの「”Swift”メソッドの変更」が該当します。
「SwiftMailer」で使用していた setReturnPath() メソッドが利用できなくなりました。
setReturnPath() は、メール送信に失敗した際のエラー通知先（Return-Path）を設定するメソッドです。
「Symfony Mailer」では、メールの各情報（宛先や件名など）と同様に、Return-Pathもヘッダー情報の一つとして設定する仕様になっています。
そのため、getHeaders()->addHeader() を使用して次のように対応しました。
1 2 3 | $this->withSymfonyMessage(function ($message) { $message->getHeaders()->addHeader('Return-Path', config('mail.from.address')); }); |
サイト②で対応したこと
Laravel 10 → 11：request->add によるデータ未引き継ぎ
Laravel 10 から Laravel 11 にバージョンアップした後、新規登録などのフォームで、確認画面から完了画面へ進む前にエラーが発生するようになりました。
1 | Undefined array key "name" |
最初はフォームで入力した name が取得できていないことが原因かと思いましたが、調査したところ、処理に渡されるフォームのデータ自体が空配列になっていました。
そのため、name だけでなく、他の項目もすべて取得できずエラーが発生していました。
確認画面のコードを確認したところ、リクエストにフォームのデータを追加するために SymfonyのParameterBagである request->add() を使用していました。
1 | $request->request->add($arrForm); |
これを merge() を使用するように変更しました。
1 | $request->merge($arrForm); |
変更したところ、フォームで入力した値が正しく次の処理へ引き継がれ、完了画面まで表示されるようになりました。
他の画面でも同じ問題が発生していたため、->request->add( で検索し、->merge( に置換しています。
Laravel 10 → 11：dump-server による composer エラー
Laravel 10 から Laravel 11 にバージョンアップした際、composer update を実行したときにエラーが発生しました。
1 2 3 4 | Your requirements could not be resolved to an installable set of packages. Root composer.json requires beyondcode/laravel-dump-server ^1.0 Root composer.json requires laravel/framework ^11.0 |
こちらは beyondcode/laravel-dump-server が Laravel 11 に対応していないことが原因でした。
また、このパッケージはデバッグのための機能を提供するものですが、LaravelはもともとSymfony VarDumperを利用しており、dump() / dd() の機能でデバッグ可能なため、このパッケージ自体が不要になっていました。
composer.json の該当パッケージ（"beyondcode/laravel-dump-server": "^1.0"）を削除した後、composer update を実行することでエラーは解消されました。
Laravel 10 → 11（Carbon 3）：diffInSeconds の仕様変更
エラーではありませんが、Laravel 11 にバージョンアップした際に見落としがちな変更として、日付操作ライブラリである Carbon の仕様変更があります。アップグレードガイドの「Carbon3」が該当します。
Laravel 11 では Carbon 2 と Carbon 3 の両方がサポートされていますが、Carbon 3 にアップグレードする場合、diffIn* 系メソッドの挙動が変更されています。
主な変更点は以下の通りです。
- 戻り値が
int型からfloat型に変更 - 差分が絶対値ではなく相対値（符号あり）になる
例えば diffInSeconds() の場合、Carbon 2 では常に正の値が返っていましたが、Carbon 3 では時間の前後関係によって負の値になることがあります。
今回の事例では、次のように時間の差分を取得していました。
1 | $item->update_date->diffInSeconds($now, true); |
この処理について、以下のように修正しています。
- 整数で扱えるよう
int型にキャスト - 第2引数を省略し、符号付きの相対値として扱うように変更
1 | (int) $item->update_date->diffInSeconds($now); |
