はじめに
突然ですが、皆様はLumenというフレームワークをご存知ですか？
LumenはLaravelをベースにしたマイクロフレームワークで、軽量ながらLaravelのコア機能の一部を利用できるフレームワークとして、弊チームでも使用していましたが、今回LumenからLaravelへ移行するという大きな決断をしました。
この記事では、
- なぜLaravelへの移行が必要だったのか
- 情報があまりない状態から、どのように技術的な調査を行い、移行計画を立てたか
といった、意思決定のプロセスと具体的な準備について、現在進行形で取り組んでいる内容を共有します。同じようにLumen→Laravelの移行について悩んでいる方の参考になれば幸いです。（もうLumenを使用されているケースは稀だと思いますが・・笑）
なぜLumenからLaravelへ移行を決意したか
そもそも「Lumenとは？」という方のために、念のためLumenの概要を載せておきます。
Lumenとは？
Laravelをベースにしたマイクロフレームワークで、Laravelのコア機能の一部を利用できます。具体的には、ルーティング、依存性注入、Eloquent ORM、キューイングなどの機能が利用可能です。Laravelのフル機能が必要ない、より軽量なAPIやマイクロサービス開発に適しています。
弊バックエンドチームのAPIの一部に Lumen 9.x を使用していました。特に致命的なバグがあったわけではありません。しかし、最後にバージョンアップしたのは2022年。EOLを過ぎているこの状況を前に、腰を据えてバージョンアップ対応を決意しました。
また、Lumenは最新のLaravel12.xを追従した 12.xがリリースされておらず、最新でも11.xまでの追従しかされていません。
「とりあえずLumenの最新版までバージョンアップすれば良いっしょ！」
とも思ったのですが、
- セキュリティリスクの増大: 今後のメジャーアップデートが不透明な状況で、フレームワーク本体のセキュリティフィックスが遅れる恐れ
- 保守性の低下: Laravelでは当たり前に使える便利な機能などが利用できず、開発体験が低下する恐れ
- 技術的負債の蓄積: いずれは移行せざるを得ない状況で、先延ばしにすればするほど移行コストが増大する
Lumenを使い続けることは、将来的なメンテナンスや機能追加においてリスクを伴う可能性があり、Laravelへの移行がアプリケーションの持続可能性と発展性の観点から推奨される選択肢と判断しました。
※ ちなみにLumen公式からもLaravelへの移行推奨（最新のLaravel12系を追従していない）
Laravel移行への道筋を考える
「LumenからLaravelへの移行したい」という想いとは裏腹に、
- 未知との遭遇: チーム内で誰も経験がなく、工数が見えない
- 参考情報の皆無: 参考になる記事がほぼない（あってもかなり古いレベル）
- 工数の兼ね合い: チーム内でバージョンアップ対応に割ける工数は、基本自分1人。Laravel Shiftの利用も検討したが予算や社内申請の都合上、今回は自力でやる方針
というチーム状況だったため、まずは「どういう方針で、何からどう進めるか」を明確にすることから始めました。まさに「戦いたいけど敵を知らない状態」だったので、まずは「敵を知る」ことが必要でした。
また、大きな変更になるため、技術的な実現可能性の調査はもちろん、チーム全員が理解、納得した状態で進むための合意形成も重要視しました。
Step 1: Deep Researchを活用
まず、私が行ったのはAIの力（主にDeep Research）を借りて、「LumenとLaravelの違い」を洗い出し、移行の難易度と影響範囲を具体化することでした。
こんなようにリサーチ結果をベースに変更点を把握しながら「そもそもどういう変更と影響があるんだっけ？」と自身も理解を深めました
※ 実際のdeep researchのドキュメント
この調査で特に影響が大きいと判明したのが、以下の点です。（一部抜粋）
-
ディレクトリ構造の根本的な違い:
bootstrap/app.phpの役割が全く異なり、設定ファイルの読み込み方から見直す必要がありました。 -
設定 (
config) の思想の違い: Lumenのシンプルな設定から、Laravelのサービスごとに分割された詳細な設定ファイル群への移行が必要でした。
これらの調査結果をわかる範囲でドキュメントにまとめ、
「何を」「なぜ」「どのように」変更するのかが分かる状態を目指しました。
Step 2: 移行計画の作成
加えて、弊チームでは最終的に「Laravel最新版まで追従しよう」という想いがあったので、Lumen→Laravelへの移管だけでなく、移行後の「Laravel自体のバージョンアップとそれに伴うPHPのバージョンアップ」も計画に含める必要があります。
そこでGeminiなどのAIと壁打ち、調査をしながら以下のような段階的移行プランを立案しました。
-
Laravel 9への移行:- まずはLumen 9のベースであるLaravel 9のプロジェクト構造に書き換える。
-
Laravel 10へのバージョンアップ:- Laravel 9への移行が完了したら、公式のアップグレードガイドに沿ってLaravel 10へ上げる。
PHP 8.2へのバージョンアップ:Laravel 11へのバージョンアップ:Laravel 12へのバージョンアップ:PHP 8.4へのバージョンアップ:
※ 実際の手順書ドキュメントの一部（概要版）
💡なぜ段階的に実施したのか？
一気に最新のLaravel 12を目指すことも可能でしたが、ビッグバンリリースや問題が発生した際の切り分けが困難になるリスクを考慮し、段階的なアップグレードを選択しました。各メジャーバージョンで一度動作確認を挟むことで、安全かつ着実に移行を進めることができるという狙いです。
✏️ なぜ最初にLumen→Laravelへの移行なのか？
LumenとLaravelは、同じコンポーネントを多く共有しているものの、ディレクトリ構造、設定方法、ブートストラッププロセス、デフォルトで有効な機能などが異なります。最初に同バージョンのLaravelへ移行することで、これらの構造的な差異に起因する問題を特定しやすくなり、その後の段階的なバージョンアップグレードをよりスムーズに進めることができます。
Step 3: チーム内での認識統一
作成した「移行ガイド」を元に、バックエンドメンバーへの相談/レビューを行いました。
- 現状のリスク: このままLumenを使い続けることのデメリット
- 移行のメリット: Laravelに移行することで得られる恩恵
- 具体的な移行計画: ステップ・バイ・ステップの計画
- 想定されるリスクと対策: 移行作業中に考えられる問題
- 見積もり工数:（可能であれば「調査にX日、移行作業にY人日」など）
チームメンバーは、自分よりPHP/Laravelへの知見があるメンバーだったので、元々「Laravelへの移行」には共感してくれており、特に進め方の差し戻しや大幅軌道修正もなく、移行に賛同してくれました。
今後について
現在は、合意した計画に基づき、まずは Lumen から Laravel、それ以降の各種バージョンアップ作業 を進めているところです。この移行が随時完了次第、改めてQiitaで技術的な詳細（ハマったポイントなど）を共有できればと思います。
将来的には、Laravel 12まで上げるに至る途中で出た新機能をきちんと把握し、ただ動くように書き換えるだけでなく、パフォーマンスや可読性の観点で既存のソースコードのリファクタリングも行っていければと思います。
おわりに
今回は、LumenからLaravelへの移行を決断するに至った背景と、各種バージョンアップ対応の計画策定プロセスについてご紹介しました。
今回、自分の場合はdeep researchを活用して移行計画の立案や変更点、影響範囲の調査を行っていましたが、このおかげでかなり時間短縮につながったと思います。
もはやマイナー? なLumenを今からLaravelへ移管する事例は少ないかもしれませんが、言語やフレームワークは違えど、何かしら大幅なバージョンアップやフレームワークの移行をする場合でも、何か参考になれる点やきっかけになれば幸いです。
最後までお読みいただきありがとうございました！
順次バージョンアップについての記事も投稿予定ですのでお楽しみに！