最終更新日 2020年2月13日

Twig 公式ドキュメントより：
「マクロは一般のプログラミング言語の関数と似ています。頻繁に使用される HTML 構文を再利用可能な要素として設定するのに便利です。」

{% macro input(name, value, type, size) %}
  <input type="{{ type|default('text') }}" name="{{ name }}" value="{{ value|e }}" size="{{ size|default(20) }}" />
{% endmacro %}

マクロはネイティブの PHP 関数といくつか異なる点があります：

• デフォルトの引数値は 、マクロ本体の default フィルタを使用して定義されます。
• マクロの引数は常にオプションです。
• 余分な位置引数がマクロに渡されると、それらは値のリストである特別な varargs 変数になります。

しかし PHP 関数と同様に、マクロは現在のテンプレート変数にアクセスすることはできません。特殊な_context 変数を使用して、コンテキスト全体を引数として渡すことは可能です。

マクロの呼び出し方

_self から

マクロの呼び出し元である twig に、マクロを配置することが可能です。この場合、_self コンテキストを利用します：

{{ _self.input(name, value, type, size) }}

外部ファイルから

ただし、マクロの呼び出しは別ファイルから行うことがベストプラクティスとされます。これは、マクロを複数のテンプレートで利用可能にできるからです。

例えば、"mytheme" というカスタムテーマ内には、以下のようにマクロを追加することができます：

[site_root]/themes/custom/mytheme/templates/macros.twig

注意事項：マクロのファイルは ".twig" という拡張子であればどのような名前でも構いません（例：anything.twig）。ただし ".html" という拡張子を使うことはできません（つまり anything.html.twig と命名した場合は機能しません）。また、マクロファイルは実際にどこで使われるかに関わらず、必ず "templates" ディレクトリに格納されている必要があります。例えばレイアウトビルダーのレイアウトを mytheme/layouts に格納した場合、マクロは mytheme/templates に格納される必要があります。

マクロを利用したいテンプレートには、以下のインポート宣言を埋め込む必要があります：

{% import '@mytheme/macros.twig' as myMacros %}

@mytheme は自動的にテーマの "templates" ディレクトリの場所を特定しますが、それ以外のディレクトリ構造は別途インポート宣言で設定する必要があります：

{% import '@mytheme/foo/bar/macros.twig' as myMacros %}

注：このドキュメントの以前のバージョンでは、階層化されているディレクトリーは不要であると記されていたため、上記の説明と実際の状態が異なる可能性があります。もしこれをカスタムモジュール内で行う場合、上記で説明されている手法をそのまま使い、テーマ名をモジュール名に置き換得ることで対応できます(例：@mycustommodule）

上記を踏まえた際のマクロの記述は以下のように行います：

{{ myMacros.input(name, value, type, size) }}

実例

Drupal コアにおいては、マクロはメインナビゲーションなどに使われています。menu.html.twig を参照してください。