こんにちは！Booost株式会社Webエンジニアのramcursweです。
先日、Laravelのバージョンアップ作業（10→12）を行ったのですが、その際に日付や時間を扱うライブラリのCarbonについて注意すべき点がありましたので、備忘および共有としてまとめたいと思います。
Carbon3の注意点
・Laravel 12.x アップグレードガイド（Carbon3）
アップグレードガイドには「影響の可能性： 低い」と記載されています。
また、「Carbon2.xのサポートを削除しました。すべてのLaravel 12アプリケーションはCarbon 3.xを必須にしました。」とサラッと書かれています。
しかし、Carbonの公式ドキュメントを見ると、サラッと流してはいけないことが分かります…
・Carbon公式ドキュメント（Migrate to Carbon 3）
実際にコードで確認した方が分かりやすいので、以下に例を挙げます。
（例）
$start = Carbon::parse('2025-08-08');
$end = Carbon::parse('2025-09-08');
// Carbon2では
$monthsDifference = $start->diffInMonths($end); // 1
$monthsDifference = $end->diffInMonths($start); // 1
// Carbon3では
$monthsDifference = $start->diffInMonths($end); // 1.0
$monthsDifference = $end->diffInMonths($start); // -1.0
diffIn系メソッドに関し、Carbon2では常に正のintが返却されていましたが、Carbon3では符号付きfloatが返されるようになります。
つまり、意図せず小数点付き数値やマイナス値になってしまう可能性があります！
影響の可能性が低いとは…
今回のバージョンアップにあたり、既存の実装箇所で意図しない数値になるのを防ぐため、次の例のようにintキャストと絶対値化を実施しました。
$start = Carbon::parse('2025-08-08');
$end = Carbon::parse('2025-09-08');
// 返却値はintであり、マイナスにならない
$monthsDifference = (int) $start->diffInMonths($end, absolute: true) // 1
$monthsDifference = (int) $end->diffInMonths($start, absolute: true) // 1
これで既存箇所に悪影響が出ないようにできました！
学び
アップグレードガイドはもちろん、関連するライブラリの公式ドキュメントもしっかり読む必要があると強く実感しました。
また、既存で影響が出そうな箇所をAIを使って洗い出すことで、作業効率を高めることができました。
これからもAIは作業のお供として、どんどん有効活用していこうと思いました。
Discussion