FormAlter as Plugin
従来のhook_form_alter()実装をオブジェクト指向のPluginに置き換える、Plugin ベースのフォーム変更システムを提供します。
pluginformalter
インストール
composer require 'drupal/pluginformalter:8.x-1.8'
composer require 'drupal/pluginformalter:8.x-1.7'
概要
FormAlter as Pluginは、Drupalフォームの変更方法を現代化する開発者向けユーティリティモジュールです。従来の手続き型hook_form_alter()アプローチの代わりに、アノテーションを使用したオブジェクト指向のPluginを作成してフォームを変更できます。このアプローチにより、コード構成の改善、Dependency Injectionのサポート、関心の分離の明確化が実現します。
このモジュールは3種類のフォーム変更をサポートしています：標準的なDrupalフォーム（form_idまたはbase_form_idによる）、Paragraphsウィジェットフォーム（paragraph_typeによる）、Inline Entity Formフォーム（entity_typeとbundleによる）。各Pluginタイプには独自のアノテーションとマネージャーサービスがあり、特定のフォームを正確にターゲットにできます。
さらに、このモジュールはWebprofilerモジュールと統合されており、デバッグツールバーで各フォームを変更しているPluginを表示するため、開発とデバッグが容易になります。
注意： Drupal 11.2以降、Drupal CoreがOOP Hookをネイティブにサポートするようになったため、このモジュールは非推奨警告を発生させます。このモジュールはDrupal 12.0.0で動作しなくなるため、開発者はCoreのOOP Hookに移行する必要があります。
Features
- hook_form_alter()をオブジェクト指向アプローチに置き換えるPluginベースのフォーム変更システム
- ワイルドカードマッチングによるform_idまたはbase_form_idでのフォームターゲティングをサポート
- Paragraphsモジュール統合によるParagraphタイプウィジェットフォームの変更
- Inline Entity Formモジュール統合によるIEF Entityフォーム、参照フォーム、テーブルFieldの変更
- フォーム変更の順序を制御するためのweightベースのPlugin順序付け
- 複数のPluginが予測可能な実行順序で同じフォームを変更可能
- デバッグツールバーにすべてのFormAlter Pluginを表示するWebprofiler統合
- ContainerFactoryPluginInterfaceによる完全なDependency Injectionサポート
- ローカライゼーションサポートのためのStringTranslationTraitをベースクラスに含む
Use Cases
ドメイン別のフォーム変更整理
アプリケーションの各機能領域に対して個別のFormAlter Pluginを作成します。例えば、ログイン変更用のUserLoginFormAlter、コンテンツ編集用のNodeFormAlter、ECサイト用のCommerceCheckoutFormAlterを作成します。各PluginはDependency Injectionによりロジックを明確にカプセル化します。
すべてのNodeフォームの変更
base_form_idターゲティングを使用して、すべてのNodeフォームを一度に変更します。@FormAlter(id = "node_form_base_alter", base_form_id = {"node_form"})でPluginを作成し、すべてのコンテンツタイプにカスタムバリデーションやField変更などの共通機能を追加します。
条件付きフォーム変更
Pluginシステムとformater()メソッド内の条件ロジックを組み合わせます。Pluginはターゲットフォームがレンダリングされるときにのみインスタンス化され、実装内で追加の実行時条件を追加できます。
特定のParagraphタイプのターゲティング
Paragraphsモジュールを使用する場合、ParagraphsFormAlter Pluginを作成して特定のParagraphタイプフォームをカスタマイズします。例えば、画像Paragraphウィジェットを変更してカスタムJavaScript動作やバリデーションを追加します。
Inline Entity Formの拡張
InlineEntityFormAlter Pluginを使用して、フォームにEntityが埋め込まれる方法をカスタマイズします。特定のEntityタイプとbundleをターゲットにしたり、Entity参照リストのテーブルField表示を変更したりします。
変更順序の制御
複数のPluginが同じフォームを変更する場合、weightプロパティを使用して実行順序を制御します。weightが低いものが先に実行されます。これは、ある変更が別の変更の結果に依存する場合に不可欠です。
フォーム変更のデバッグ
Webprofilerが有効な場合、モジュールはデバッグツールバーに各フォームに影響を与えるすべてのFormAlter Pluginを表示します。これにより、どのPluginがフォームを変更しているかを特定し、予期しない動作を追跡できます。
Tips
- Pluginクラスは検出されるためにsrc/Plugin/FormAlter/ディレクトリに配置する必要があります
- form_idでワイルドカードパターン（例：'node_*_form'）を使用して複数のフォームをターゲットにできます
- ベースクラスFormAlterBaseには便利なStringTranslationTraitとDependencySerializationTraitが含まれています
- ContainerFactoryPluginInterface（FormAlterBaseに含まれる）を実装してPluginにサービスを注入します
- Pluginはform_idとbase_form_idの両方のターゲティングをサポートし、base_form_idの変更はform_idの変更より先に実行されます
- Drupal 11.2以降では、このモジュールの代わりにCoreのOOP Hook機能への移行を検討してください
- Pluginを追加または変更した後、変更を反映するためにCacheをクリアしてください
Technical Details
Hooks 1
pluginformalter_form_alter_info_alter
3つのPluginマネージャーのいずれかで検出されたFormAlter Plugin定義を変更します。
Troubleshooting 5
Pluginが正しい名前空間（Drupal\yourmodule\Plugin\FormAlter）にあること、正しいアノテーション（@FormAlter、@ParagraphsFormAlter、または@InlineEntityFormAlter）があること、すべてのCacheをクリアしていることを確認してください。
Pluginアノテーションのweightプロパティを調整してください。weightが低いものが先に実行されます。必要に応じてpluginformer_form_alter_info_alter Hookを使用して実行時にweightを変更できます。
これらの警告は、モジュールがDrupal CoreのOOP Hookを優先して非推奨になったことを示しています。Drupal 12にアップグレードする前に、Coreのhook_form_alter OOP実装への移行を計画してください。
pluginformalterとwebprofilerの両方のモジュールが有効になっていることを確認してください。Cacheをクリアして、サービスプロバイダーがformsデータコレクターを正しくデコレートしていることを確認してください。
@ParagraphsFormAlterアノテーション（@FormAlterではない）を使用していること、paragraph_typeが正確に一致していることを確認してください。paragraph_typeはParagraphタイプのマシン名である必要があります。