こんにちは！
ホワイトプラスのコアシステム開発Gエンジニアのさとうです。
先日 abandoned（放棄）となった laravelcollective/html を spatie/laravel-html に移行する作業を行いました。
プロダクトコード内における laravelcollective/html の使用箇所は約1,700箇所...！
手作業で置き換えるには中々骨の折れる数です。
そこで、laravelcollective/html のドキュメント内で推奨されていた置換ツール「Shift」を用いて移行することにしました。
この記事では、laravelcollective/html から spatie/laravel-html への移行を例に、Shift の利用方法をお伝えします。
Shift は laravelcollective/html の移行だけでなく、Laravel や PHPUnit のバージョンアップ対応も行えるので、移行・バージョンアップを検討中の方にご覧いただけると幸いです。
laravelcollective/html と spatie/laravel-html
laravelcollective/html とは？
laravelcollective/html は HTML とフォームジェネレーターが同梱されているパッケージです。
blade ファイルで簡単にフォームを管理したり、複雑なモデルをフォームにバインドしたりすることができます。
Laravel 4まではデフォルトで利用できていましたが、Laravel 5以降デフォルトから外されて、別管理でメンテナンスされるようになりました。
2023年にはパッケージが abandoned（放棄）になるとアナウンスされ、Laravel 11以降はサポートされなくなっています。
The Laravel Collective recently announced that they are abandoning the project, and once Laravel 11 is out, it'll no longer work.
Laravel Collective HTML package is abandoned - Laravel News
spatie/laravel-html
laravelcollective/html の移行先として挙げられているのが spatie/laravel-html です。
If you've been using the laravelcollective/html package, its now time to update it and move to the spatie/laravel-html package.
Laravel Collective HTML package is abandoned - Laravel News
spatie/laravel-html は laravelcollective/html と似ているものの、API が異なるため、移行には作業を要します。
laravelcollective/html を廃止する方法は3つ挙げられています。
- 手動で spatie/laravel-html に変換する
- 生の HTML に変換する
- 移行ツール「Shift」を用いて自動変換する
This will be a manual conversion because although the packages are similar, both APIs differ. If you are using it in a few places, it would be easiest to convert to raw HTML.
However, if you use it substantially Laravel Shift has an automatic conversion to migrate to Spatie HTML which can save your hours of work.
Laravel Collective HTML package is abandoned - Laravel News
前述した通り、プロダクトコード内には約1,700箇所の使用箇所があり、手動での置き換えや生の HTML への変換は作業コストが高いため、Shift による自動変換を選択しました。
移行ツール「Shift」の使い方
移行ツール「Shift」とは？
Shift は Laravel や PHPUnit、Tailwind などのバージョンアップや移行を自動化してくれる有料ツールです。
GitHub を連携してクラウド実行するか、Docker を使ってローカルで実行するか選択することができます。
クラウド版の方が Docker 版よりも少しお高くなっています。
Shift を使って laravelcollective/html を spatie/laravel-html に置き換える
今回はクラウド版を利用して移行を行ったので、以降でクラウド版の使い方を共有します。
laravelcollective/html から spatie/laravel-html に置き換える Shift は以下のページです。
https://laravelshift.com/convert-laravelcollective-html-to-spatie-laravel-html
1. GitHub でサインインする
クラウド版の Shift は GitHub のリポジトリからプロダクトコードを取得して実行します。
まずは GitHub で Shift にサインインしましょう。
2. リポジトリとブランチを指定する
移行したいリポジトリとブランチを指定します。
3. 決済して実行する
決済画面に移行するので、クレジットカードの情報を入力します。
これが終われば、Shift が実行されます。
実行状況は Shift 上で確認できます。
実行待ちの画面は以下のような状態です。
実行に成功すると STATUS に PR 番号が表示されます。
GitHub を見てみると、移行作業の PR が自動的に作成されていることが確認できます。
実行に失敗すると STATUS に Issue や Failed と表示されます。
Shift を使う上での注意点
対応バージョンに要件がある
Shift で laravelcollective/html から spatie/laravel-html への自動変換を行うには、以下の要件を満たしている必要があります。
- Laravel 10.x 以上であること
- laravelcollective/html のバージョンが 6.4 以上 であること
composer.json と view ディレクトリの位置に注意
Shift はリポジトリのルートに composer.json があることを前提に自動変換を実施します。
なので、ルート以外に composer.json を置いている場合は、Shift に composer.json のありかを伝える必要があります。
.shiftrc ファイル（中身は空で構わない）を composer.json があるディレクトリに置くことで、Shift に基準となるディレクトリを伝えることができます。
例えばリポジトリ内で Laravel 以外のディレクトリもある場合は、以下のように .shiftrc ファイルを配置してみてください。
├ .git
├ infrastructure/
└ backend/
├ composer.json
└ .shiftrc # ここに空の.shiftrcファイルを設置
また、composer.json を置いてあるディレクトリ以下の view ディレクトリ以外に変換対象がいる場合は少し工夫が必要です。
例えば、以下のようなディレクトリ構成の場合で説明します。
├ .git
├ laravel/
│ ├ composer.json
│ └ resources/
│ └ views/
│ └ target1.blade.php
└ others/
└ resources/
└ views/
└ target2.blade.php # 変換対象外
このようなディレクトリ構成の場合、laravel ディレクトリに .shiftrc ファイルを設置すると target1.blade.php は変換されますが、target2.blade.php は変換されません。
この場合は、リポジトリのルートにダミーの composer.json を設置することで配下のディレクトリすべてを変換対象にできます。
├ .git
├ composer.json # ダミー
├ .shiftrc # 念の為
├ laravel/
│ ├ composer.json
│ └ resources/
│ └ views/
│ └ target1.blade.php
└ others/
└ resources/
└ views/
└ target2.blade.php # 変換対象になる
ダミーの composer.json は以下のように laravelcollective/html の依存を記載する必要があります。
{ "require": { "laravelcollective/html": "^6.0" } }
以上により、さまざまなディレクトリに散らばった変換対象も変換できるようになりますが、肝心の laravelcollective/html から spatie/laravel-html への移行はダミーの composer.json を対象に行われてしまいます。
ダミーの composer.json を用意した場合は、別途手動で laravelcollective/html の削除と spatie/laravel-html のインストールを行ってください。
問い合わせは英語でやり取り
前述の composer.json と view ディレクトリの問題解消と Shift の再実行を依頼するためにサポート窓口にメールで連絡しました。
サポートとのやり取りは英語で行うことになります。
翻訳や LLM が便利になってきているので、恐れることはあまりないかもしれませんが、念頭においておくと良いかもしれません。
メールは何通かやり取りしましたが、基本的に1日以内に返信が返ってきたので、何日も放置されるようなことはなさそうです。
まとめ
この記事では、laravelcollective/html から spatie/laravel-html への移行を例に、Shift の利用方法をお伝えしました。
ディレクトリ構成をカスタマイズしていたため、苦労した部分もありました。
しかし、約1,700箇所の対応を人手でやることを想像すると気が遠くなるので、苦労して自動化した甲斐はありました。
Shift は laravelcollective/html から spatie/laravel-html への移行以外にも Laravel や PHPUnit のバージョンアップもできるので、対応を予定している方は利用を検討してみてはいかがでしょうか。
今回の情報共有が、今後 Shift を使う方々のお役に立てれば幸いです。
さいごに
ホワイトプラスでは、ビジョンやバリューに共感していただけるエンジニアを募集しています！
ネットクリーニングの「リネット」など「生活領域×テクノロジー」で事業を展開している会社です。
どんな会社か気になった方はオウンドメディア「ホワプラSTYLE」をぜひご覧ください。
オンラインでカジュアル面談もできますので、ぜひお気軽にお問い合わせください。
