概要

Laravelのバージョンアップを苦労しながらやりとげたので、調査・検証方法を備忘録がてらまとめてみます。

背景

Laravel9から10へのバージョンアップは、想像以上に苦労しました。
振り返ってみると調査が足りなかったり、バージョンアップに伴って何をするべきなのか全容が見えていないように感じました。

そこで、今後はサクサクバージョンアップできるよう、調査・検証で何をするのが良さそうか方針を整理しておきます。

ゴール

Laravelのバージョンを上げるとき、何を調べ、どうやって検証していくのかイメージできるようになることを目指します。

バージョンアップに向けてやること

まずは全体像を掴むために、やることを書き出しておきます。
調査・検証の目的を一言にまとめると、バージョンアップ後もLaravelアプリケーションが問題なく動くようにするためです。

これを実現するには、バージョンアップで何が変わるか明確にしなければなりません。
変わるものはLaravelのバージョンだけでなく、非推奨となった機能・パッケージも含まれています。何が変わるのか調査段階で一通り洗い出しておきます。

そして、変更された点をLaravelアプリケーションへ反映させ、今まで通り動く状態をつくりだしていくのが検証作業です。

それぞれで具体的に何をすれば良いのか、本記事で理解を深めていこうと思います。

調査

調査では、Laravelのバージョンが上がると何が変わるのか明らかにすることを目指します。
変更内容が見えてくれば、どれだけの時間が掛かるのか見積もれるはずです。

最初の一歩-Upgrade Guideを読む

Laravel公式によって書かれたアップグレードガイドを読むことから始めます。
各節を見ながら、アプリケーションが関係しそうな箇所にアタリをつけておきます。

Composerや依存パッケージのバージョンから始まり、Laravel自体の機能も広く書かれているので、
アップグレードガイドに従っていけば、バージョンアップでやるべきことも見えてきそうです。

と言いたいところですが、アップグレードガイドだけでは変更点を網羅できませんでした。
もう少し調査範囲を広げなければなりません。

非推奨となった機能を知る

アップグレードガイドに書いていて欲しいところですが、Laravelにはバージョンが上がると非推奨になってしまう機能があります。

非推奨の機能はコード自体から削除されるため、そのまま放っておくと実行時エラーを招くおそれがあります。
よって、漏れなく取り除いておきたいところです。
何が非推奨なのかは、Laravel本体のプルリクエストを見るのが確実です。

ですが、ざっくり対象を知っておきたい場合は、Laravel Newsというサイトに情報がまとまっているので、おすすめです。
参考
削除されたコードが含まれるプルリクエストへのリンクをまとめてくれているので、今回の調査でも参考になりました。

依存パッケージまで面倒を見る

ここまでの調査では、Laravel本体および、Laravel標準パッケージまでを見てきました。
続いて、Laravel標準以外のパッケージにも目を向けます。

とくに、新しいバージョンのLaravelでサポートされなくなったパッケージに注意しておきます。
例えば、Laravel10へ上げたときには、laravel-corsというパッケージがサポートされていないことが発覚しました。

サポートされていないパッケージは代替のパッケージを導入するか、Laravelの機能で補うことになります。
具体的な方針は、各パッケージのREADMEなどに書かれているので、目を通しておきます。

とりあえずバージョンアップ

とはいえ、導入しているパッケージすべてを一つ一つ点検するのは骨が折れます。
そこで、細かいことは後にしてとりあえずLaravelのバージョンを上げてみます。

依存パッケージの点検

LaravelはComposerパッケージとして管理されているため、Composer関連のコマンドからバージョンを上げることにします。
いきなりLaravelのバージョンを上げたいところですが、サポートされなくなったパッケージが含まれていると互換性が無い旨のエラーが表示されてしまいます。

ですので、まずはcomposer installコマンドで現行のパッケージを点検します。

1$ composer install
2# 中略...
3Package fruitcake/laravel-cors is abandoned, you should avoid using it. No replacement was suggested.
4Package laravelcollective/html is abandoned, you should avoid using it. Use spatie/laravel-html instead.

コンソールの出力の末尾にサポートが終了したパッケージ情報が書かれています。
該当のパッケージはひとまずcomposer.jsonから取り除いておきます。

こうすることで、変な競合を気にせずLaravelを更新できるようになります。

バージョンアップ

今度こそLaravelのバージョンを上げます。
Composerで依存パッケージのバージョンを変更したい場合は、composer updateコマンドを実行します。
まずはLaravel本体であるlaravel/frameworkのバージョンだけを上げておきます。

参考

1$ composer update "laravel/framework"

上手くいけば、依存パッケージと共存しながらLaravelのバージョンが上がってくれるはずです。

静的解析・ユニットテストで問題を探したい

Laravelのバージョンを事前に上げてみるだけでもさまざまな問題を検出できます。
ですが、動かしてみて初めて発覚するような問題もまだまだ潜んでいます。

そこで、環境が整っているのであれば、バージョンアップ後の環境で静的解析やユニットテストを実行しておきます。
ここまで動かしておくと、影響が大きそうなエラーや警告は大体検出できるはずです。

調査でやることまとめ

以上の手順を踏んでいけば、Laravelのバージョンが上がったとき、どこに影響が及ぶか見えてきそうです。
意外とやることがたくさんあったので、ここまでの手順を振り返っておきましょう。

• 公式のアップグレードガイドを読んでおく
• Laravel本体のプルリクエストを参照できる情報源から、非推奨となった機能を点検
• とりあえずバージョンを上げてみて、依存パッケージでサポートされなくなったものが無いか検証
• 静的解析・ユニットテストを実行し、Laravelのバージョンが上がることで起きる問題を検出
• バージョンアップ後のLaravelアプリケーションも問題なく動作させるには、何をすればいいのか見積もる

影響を調べ、対処にどの程度掛かるか見積もるのは、Laravelアプリケーションの改修と同じような流れでした。
ですが、情報源が色々あったり、依存パッケージの扱いが慣れていないと見落としそうであったり、ハマりどころもいくつかありました。

今後Laravelのバージョンを上げるときは、上記観点にて何が変わるか漏れなく網羅していきたいです。

検証

ここからは、調査を終え、実際に作業することになったときにやることを記します。

動かせる状態をつくる

検証のゴールは、Laravelアプリケーションがバージョンアップ後もこれまで通り動く状態とする、といったところに見据えます。

よって、どうやったら動く環境が手に入るのか、掘り下げていきます。

Laravelのバージョンアップ

最初に、調査のときと同じ手順でLaravelのバージョンを上げるところから始めます。
バージョンを上げたあとにアプリケーションを動かすと、たくさんの問題が検出されます。

ですので、問題の種類に応じて1つ1つ確実に対処していきます。

非推奨機能

非推奨な機能は、クラス自体が削除されていることが多いです。
そこで、静的解析で対象を検出し、不要なものを削れば解決するはずです。

Laravelではlarastanというすてきな静的解析ツールが提供されているので、バージョンアップ作業に直面したときは、ぜひ導入してみてください。

サポート終了パッケージ

Laravelのバージョンを上げると、サポート終了として検出されてしまったパッケージに立ち向かいます。
サポートが終わるにはさまざまな理由があるので、一概に対処することはできません。

それぞれのパッケージのリポジトリを参照し、代替手段が提供されているか逐一見ていきます。

例えば、laravel-corsパッケージは、Laravel標準の機能へ置き換える手順をリポジトリにて書いてくれています。

今回経験したバージョンアップでは、互換性の無いパッケージにとても苦しめられました。
とてつもなく苦労したので、ハマったところは補足に書いておきます。

変更された機能の置き換え

アップグレードガイドでは、一部の機能の書き方が変わったものも言及されています。
今回経験したバージョンアップでは、Database Expressionsという機能に関わる書き方が変更されていました。

参考

このような場合は、静的解析やComposerなどで検出するのは困難です。
しかし、実行時エラーが発生するような深刻な問題でした。

今回は運良く見つけられましたが、思いもよらない問題が潜んでいることもあるので、テストで確実に見つけたいところです。

検証作業でやることまとめ

検証作業は、調査したときに見繕った問題に対処するのが主な作業でした。
やることこそ明確ですが、どれも大事な手順なので何をするか整理しておきましょう。

• まずはLaravelのバージョンを上げる
• 非推奨の機能は大体削れば良いだけなので、静的解析で見つかったものを削除
• パッケージのサポートが終わってしまったものは、個別に案内に従って置き換え
• 変更された機能で影響を受けそうなものがないか点検

補足: とくに厄介だったパッケージ

ここでは、Laravelを9から10へ上げたときに特に苦戦したパッケージlaravelcollective/htmlについて書いておきます。
当該パッケージは、Form::open()のような記法でフォーム描画をサポートしてくれていました。
ですが、サポートが終わってしまったことから、Laravelのバージョンを上げると下記のような警告が表示されました。

Package laravelcollective/html is abandoned, you should avoid using it. Use spatie/laravel-html instead.

警告に従えば、spatie/laravel-htmlなるパッケージに移行すれば良さそうです。
しかし、このパッケージはAPIの書式に互換性を持たないため、入力フォームを持つすべての画面を手直ししなければなりませんでした。

パッケージが提供している機能はBladeテンプレートで十分に実現できるものだったので、パッケージ自体を削除することにしました。
より具体的には、該当のパッケージを参照しているコードを以下のようなイメージで書き換えました。

1// 変更前
2Form::text('name', 'value', ['id' => 'text']);
3
4// 変更後
5@include('inputs.text', ['name' => 'name', 'value' => 'value', 'options' => ['id' => 'text']);

少し周りくどいように見えますが、このように元の書式を残しておくことで、正規表現を利用した一括置換で変更できます。
すると、一つの入力フォームで動作が確認できれば、あとは同じ正規表現で置き換えることで、安心してパッケージが提供する機能と同じ振る舞いが実現できるようになります。

互換性の無いパッケージへ移行されると、検証がとても大変になるので、インストールするパッケージが継続してサポートしてくれそうか、本当に必要なものなのか、しっかり吟味したいですね(;

テスト

とりあえず動くようになったのも大きな一歩ですが、まだ安心できません。
バージョンアップ以前の振る舞いが漏れなく実現できているか確かめることで、本番環境で自信をもってバージョンをあげられるようにしたいところです。

以降では、本番環境のLaravelのバージョンを上げるまでに、どうやって検証するか方針を記します。

基本はユニットテスト

振る舞いが変わっていないか検証するには、ユニットテストが最適です。
重要なビジネスロジックは、PHPUnitによるユニットテストで漏れなく確実に確認しておきたいところです。

最後の手段-手動確認

ユニットテストに加えてE2Eテストもあれば、画面操作も含めてより堅牢に振る舞いを確認できそうです。
ですが、自動テストだけでは十分に振る舞いが網羅されていない場合もあります。

そんなときは、手動テストで見ていくしかありません。
アプリケーションが提供する機能を表などにまとめ、1つ1つ点検していくことになるでしょう。

LaravelではLTSが廃止されてしまったので、今後はこまめなバージョンアップが必要そうです。
都度手動で確認していると効率が悪いので、少しずつでもテストを書くようにしたいですね(:

まとめ

本記事では、Laravelのバージョンを上げることになったとき、何をすれば良いか迷わないよう、
やるべきことをざっくりとまとめました。

バージョンアップに直面した方、そして、Laravel11へ上げることになる未来の自分へ役立てれば幸いです。