はじめに

最近、Laravelのサービスのバージョンアップを行いました。
弊社では以前にも同様の対応を行っていたため、今回はスムーズに進めることができました。特に、laravelCollective/htmlパッケージの削除に関しては、過去のナレッジが役立ちました。

過去の記事でも削除手順について簡単に紹介していますが、この記事ではより具体的な手順を詳細に解説していきます。

これからlaravelCollective/htmlパッケージをプロジェクトから削除しようとしている方々にとって、少しでもお役に立てれば幸いです。

laravelCollective/htmlとは

まず、laravelCollective/htmlパッケージについて簡単に説明します。

このパッケージは、かつてLaravelフレームワークに標準で組み込まれていたHTMLフォーム生成やヘルパー機能を提供します。Laravel 4.xまではこれらの機能がデフォルトで利用可能でしたが、Laravel 5.0以降、フレームワークから除外され、laravelCollectiveによってメンテナンスされるようになりました。

このパッケージを使用すると、フォームの生成や入力フィールドの自動生成、リンクタグの生成などが容易になります。特に、フォームリクエストバインディングやCSRFトークンの自動挿入といったセキュリティ関連の機能を備えています。

しかし、Laravelの進化に伴って、laravelCollective/htmlの機能は他の手法やパッケージで代替可能となり、公式にも推奨されなくなっています。そして、Laravel11にて完全に使用できなくなるみたいです。

Laravel Collective HTML package is abandoned - Laravel News

次に、このパッケージをプロジェクトから削除する手順について、具体的に説明していきます。

削除手順

If you're looking to replace this package due to it's retirement we recommend using Shift

公式ページ によると、laravelCollective/htmlパッケージが非推奨になったため、Shiftを使って、spatie/laravel-htmlパッケージに移行することが推奨されています。

しかし、HTMLの生成にわざわざ別のパッケージを使用せずとも、生の HTML に変換することや、Bladeテンプレート等を活用することで同様の機能をシンプルに実現できます。

この記事では、以下の4パターンを元に置き換え手順を具体的に紹介します。

• Form::open と Form::close
• Form::text
• カスタムマクロの対応
• link_to

Form::open と Form::close

Form::open と Form::close の元のコード例は以下の通りです。

1{!! Form::open(['url' => 'foo/bar', 'method' => 'post']) !!}
2{!! Form::close() !!}

Form::open は、正規表現を使用して標準的な form タグに変換することができます。

こういった場合、ChatGPTなどのAIツールを活用して正規表現を生成すると、より効率的に作業を進めることができるので活用していくと良いと思います。

以下に正規表現とその置換パターンを示します。

正規表現

1\{!!\s*Form::open\(\s*\[\s*'url'\s*=>\s*'[^']+'\s*,\s*'method'\s*=>\s*'[^']+'\s*]\s*
2\)\s*!!\}

置換パターン

1<form action="$1" method="$2">@csrf

この正規表現を用いてVSCode等で置換することで、以下のように変換されます。

1<form action="foo/bar" method="post">

Form::open メソッドは内部で CSRF トークンを自動挿入しているため、通常の form タグに変換する際には @csrf を追加する必要があります。

Form::close に関しては、単純に </form> に変換するだけで対応できますので、手順の詳細は割愛します。

Form::text

Form::text も同様に、そのまま元の input タグに戻してもよいですが、該当箇所が多い場合や、複雑なHTMLを生成する場合はBladeテンプレートを活用するのが今のLaravelの主流です。

まずは以下のようなBladeテンプレートを作成します。

1<input
2    @foreach($options as $attribute => $attributeValue)
3      {{$attribute}}="{{$attributeValue}}"
4    @endforeach
5    name="{{$name}}"
6    type="text"
7    value="{{old($name) ?? $value}}"
8>

次に、作成したBladeテンプレートに合う呼び出し部分になるようにForm::textの箇所を変換します。

例えば、以下のようなサンプルコードに変更できます：

1{!! Form::text('user_name', null, ['class' => 'form-control', 'placeholder' => 'ユーザー名を入力してください']) !!}

上記のような場合は以下のような正規表現、置換パターンで上手く変換できます。

正規表現

1\{!!\s*Form::text\(\s*[^]+)\s*,\s*[^,]+)\s*,\s*[]+)\s*!!\}

置換パターン

1@include('inputs.text', ['name' => $1, 'value' => $2, 'attributes' => [$3]])

Form::radioやimageといった他の場合でも上記を参考に置き換えることで、元の同じ動作を保証することができます。

カスタムマクロの対応

laravelCollective/html パッケージを利用しているプロジェクトでは、カスタムマクロを定義している場合もあります。例えば、以下のように Form::macro を使用して独自のフォームフィールドを生成している場合です。

1Form::macro('myField', function()
2{
3    return '<input type="awesome">';
4});

このようなカスタムマクロは、BladeコンポーネントやBladeディレクティブに置き換えることができます。それぞれの実装方法は以下の通りです。

Bladeコンポーネントとしての実装

まず、Bladeコンポーネントとして実装するには、以下のようにコンポーネントファイルを作成します。

1<!-- resources/views/components/my-field.blade.php -->
2<input type="awesome">

次に、Bladeテンプレート内でこのコンポーネントを使用する際は、Form::myField(); のような呼び出し部分を以下のように変換します。

1<x-my-field />

Bladeディレクティブとしての実装

Bladeディレクティブとして実装する場合は、AppServiceProvider の boot メソッドでカスタムディレクティブを定義します。

1use Illuminate\Support\Facades\Blade;
2
3public function boot()
4{
5    Blade::directive('myField', function() {
6        return '<input type="awesome">';
7    });
8}

Bladeテンプレートでディレクティブを呼び出す際は、呼び出し部分を以下のように変換します。

1@myField

元の実装内容がUIコンポーネントのように再利用が多い場合は、Bladeコンポーネント。ロジックやPHPコードが含まれている場合は、Bladeディレクティブ。といったように、プロジェクトのニーズに応じてこれらの手法を使い分けると良いと思います。

link_to

link_to ヘルパーを標準のHTMLタグに置き換える場合、link_to のコードは以下のようになっていることが多いです。

1{!! link_to('foo/bar', 'リンクテキスト', ['class' => 'btn btn-primary']) !!}

link_to ヘルパーの場合でも同様に正規表現、置き換えパターンで変換してあげましょう。

正規表現

1\{!!\s*link_to\(\s*[^]+)\s*,\s*[^]+)\s*,\s*[]+)\s*!!\}

置換パターン

1<a href="$1" class="$3">$2</a>

これにより、以下のように正しいHTMLタグに変換されます。

1<a href="foo/bar" class="btn btn-primary">リンクテキスト</a>

この方法で、link_to ヘルパーを正確にHTMLの a タグに変換し、LaravelのBladeテンプレートに適応させることができます。

まとめ

今回紹介した手法を通じて、生のHTMLやBladeの機能に置き換えることで、laravelCollective/html パッケージを安全に削除することができます。

Laravel 11以降、このパッケージは使用できなくなるため、早めの削除をおすすめします。

不要になったパッケージや非推奨のパッケージは、定期的に見直し、最新のLaravelの機能や標準に沿った形で置き換えていくことで、プロジェクトの安定性を保つことが重要です。

この記事が、移行作業のお役に立てれば幸いです。