Components!
テーマやモジュールが定義したコンポーネントフォルダをTwig名前空間として登録し、Twigテンプレートで使用できるようにするモジュール
components
インストール
composer require 'drupal/components:^3.2'
composer require 'drupal/components:8.x-2.4'
概要
Components!モジュールは、Drupalのテーマやモジュールにおけるコンポーネント指向開発を支援する基盤モジュールです。従来のDrupalテンプレートシステムでは、テンプレートファイルは特定のディレクトリ構造に配置する必要がありましたが、本モジュールを使用することで、任意のディレクトリにあるTwigファイルに対して独自の名前空間を設定し、@namespace/template.twigの形式で簡単に参照できるようになります。
例えば、テーマのcomponents/fusionフォルダに@fusionという名前空間を割り当てると、そのフォルダ内のすべてのTwigファイルを{% include '@fusion/button.twig' %}のように呼び出せます。これにより、コンポーネントライブラリの構築、Pattern Labやストーリーブックとの統合、デザインシステムの実装が大幅に簡素化されます。
また、本モジュールは追加のTwigフィルター（recursive_merge、set、add）とTwig関数（template）を提供し、テンプレート内でのレンダー配列の操作を容易にします。さらに、Twigデバッグモード有効時にはコンポーネントの出力にHTMLコメントを自動挿入し、開発時のデバッグを支援します。
Features
- テーマやモジュールの.info.ymlファイルでカスタムTwig名前空間を定義可能
- @namespace/template.twig形式でのTwigテンプレート参照
- ベーステーマからの名前空間継承と優先順位制御
- recursive_mergeフィルター: レンダー配列の再帰的マージ
- setフィルター: ドット記法で深くネストしたプロパティを設定
- addフィルター: 既存の配列プロパティに値を追加
- template()関数: テーマフックやテンプレート名でレンダー配列を生成
- 名前空間の保護機能（他のモジュール/テーマによる上書き防止）
- hook_components_namespaces_alter()によるランタイム時の名前空間変更
- hook_protected_twig_namespaces_alter()による保護名前空間の制御
- Twigデバッグモード有効時のHTMLコメント自動挿入（コンポーネント開始/終了マーカー）
- .twig、.html、.svg拡張子のテンプレートファイルをサポート
Use Cases
コンポーネントライブラリの構築
Atomic Designパターンに従い、atoms、molecules、organismsなどの階層構造でコンポーネントを整理できます。各階層に独自の名前空間を割り当て、@atoms/button.twig、@molecules/card.twig のように参照します。これにより、大規模なテーマでもコンポーネントの整理と再利用が容易になります。
Pattern Labとの統合
Pattern LabやStorybookなどのスタイルガイドツールとDrupalテーマ間でTwigテンプレートを共有できます。両環境で同じ名前空間パスを使用することで、コンポーネントの一貫性を保ちながら開発とテストを行えます。
ベーステーマからのコンポーネント継承
子テーマは親テーマで定義された名前空間を自動的に継承します。同じ名前空間に子テーマ独自のパスを追加すると、子テーマのテンプレートが親テーマより優先されます。これにより、ベーステーマのコンポーネントを選択的にオーバーライドできます。
モジュール間でのコンポーネント共有
共通のUIコンポーネントを提供するモジュールを作成し、他のモジュールやテーマから参照できます。例えば、組織のデザインシステムモジュールを作成し、@design-system/button.twig のようにサイト全体で統一されたコンポーネントを利用します。
レンダー配列の動的操作
Twigテンプレート内でset、add、recursive_mergeフィルターを使用して、レンダー配列のプロパティを動的に変更できます。例えば、フォーム要素にクラスを追加したり、属性を設定したりする際に、複雑なwith構文やマージ操作を簡潔に記述できます。
コンポーネントのデバッグ
Twigデバッグモード（twig.debug: true）を有効にすると、各コンポーネントの出力にHTMLコメントが自動挿入されます。ブラウザの開発者ツールでこれらのコメントを確認し、どのテンプレートファイルから出力されているかを素早く特定できます。
Tips
- 名前空間名はモジュール/テーマのマシン名と異なる一意な名前を使用すると、保護名前空間の制約を回避できます
- 開発時はtwig.debugを有効にして、コンポーネントのHTMLコメントを活用しましょう
- 複数のパスを同じ名前空間に追加する場合、最初に定義されたパスが優先されます
- template()関数はレンダー配列を返すため、Drupalのキャッシュやレイジーローディングの恩恵を受けられます
- addフィルターのvalues引数を使用すると、複数のクラスを一度に追加できます
- コンポーネントファイルは.twig以外に.htmlや.svgも使用可能です（インラインSVGに便利）
- allow_default_namespace_reuseフラグはライブラリモジュールで有用です - 他のテーマがこのモジュールの名前空間を拡張できます
Technical Details
Hooks 2
hook_components_namespaces_alter
特定のテーマに対する名前空間リストを変更するフック。ランタイム時に名前空間パスの追加・変更・削除が可能です。
hook_protected_twig_namespaces_alter
保護されたTwig名前空間のリストを変更するフック。デフォルトでは、モジュールやテーマのマシン名と同じ名前空間は保護され、他の拡張機能から変更できません。このフックで保護を解除できます。
Troubleshooting 5
1. 名前空間が正しく定義されているか確認（.info.ymlのcomponents.namespacesセクション） 2. テンプレートファイルの拡張子が.twig、.html、.svgのいずれかか確認 3. パスがDrupalルートからの相対パスとして正しいか確認 4. キャッシュをクリア: drush cr
他のモジュール/テーマのデフォルト名前空間（マシン名と同じ名前空間）は保護されています。変更するには： 1. 対象モジュール/テーマがallow_default_namespace_reuseフラグを設定している場合のみ変更可能 2. hook_protected_twig_namespaces_alter()で保護を解除 3. 独自の名前空間名を使用（例: 'my_components'など一意な名前）
名前空間内に同じファイル名のテンプレートが複数存在する場合、アルファベット順で最初のものが使用されます。特定のテンプレートを使用するには、フルパスを指定します： {{ include('@components/nested2/button.twig') }}
テンプレートの優先順位は：アクティブテーマ > ベーステーマ > モジュール の順です。子テーマのパスが親テーマより先に検索されるよう、同じ名前空間に子テーマのパスを追加してください。
管理テーマがアクティブな場合、コンポーネントレジストリは管理テーマ用に構築されます。デフォルトテーマのコンポーネントが必要な場合、モジュールはデフォルトテーマのレジストリもフォールバックとして検索します。