Twig

The flexible, fast, and secure
template engine for PHP

a Symfony Product
Docs Tags macro
Docs for Twig version 1.x
Switch to another version: 2.x, 3.x
⚠️ Version 1.x is not maintained.

Table of Contents

Questions & Feedback

License

Twig documentation is licensed under the new BSD license.

macro

1.12

The possibility to define default values for arguments in the macro signature was added in Twig 1.12.

Macros are comparable with functions in regular programming languages. They are useful to reuse template fragments to not repeat yourself.

Macros are defined in regular templates.

Imagine having a generic helper template that define how to render HTML forms via macros (called forms.html):

1
2
3
4
5
6
7
{% macro input(name, value, type = "text", size = 20) %}
    <input type="{{ type }}" name="{{ name }}" value="{{ value|e }}" size="{{ size }}"/>
{% endmacro %}

{% macro textarea(name, value, rows = 10, cols = 40) %}
    <textarea name="{{ name }}" rows="{{ rows }}" cols="{{ cols }}">{{ value|e }}</textarea>
{% endmacro %}

Each macro argument can have a default value (here text is the default value for type if not provided in the call).

Note

Before Twig 1.12, defining default argument values was done via the default filter in the macro body:

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

Macros differ from native PHP functions in a few ways:

  • Arguments of a macro are always optional.
  • If extra positional arguments are passed to a macro, they end up in the special varargs variable as a list of values.

But as with PHP functions, macros don't have access to the current template variables.

Tip

You can pass the whole context as an argument by using the special _context variable.

Import

There are two ways to import macros. You can import the complete template containing the macros into a local variable (via the import tag) or only import specific macros from the template (via the from tag).

To import all macros from a template into a local variable, use the import tag:

1
{% import "forms.html" as forms %}

The above import call imports the forms.html file (which can contain only macros, or a template and some macros), and import the macros as items of the forms local variable.

The macros can then be called at will in the current template:

1
2
<p>{{ forms.input('username') }}</p>
<p>{{ forms.input('password', null, 'password') }}</p>

When you want to use a macro in another macro from the same file, you need to import it locally:

1
2
3
4
5
6
7
8
9
10
11
{% macro input(name, value, type, size) %}
    <input type="{{ type|default('text') }}" name="{{ name }}" value="{{ value|e }}" size="{{ size|default(20) }}"/>
{% endmacro %}

{% macro wrapped_input(name, value, type, size) %}
    {% import _self as forms %}

    <div class="field">
        {{ forms.input(name, value, type, size) }}
    </div>
{% endmacro %}

Alternatively you can import names from the template into the current namespace via the from tag:

1
2
3
4
{% from 'forms.html' import input as input_field, textarea %}

<p>{{ input_field('password', '', 'password') }}</p>
<p>{{ textarea('comment') }}</p>

Note

Importing macros using import or from is local to the current file. The imported macros are not available in included templates or child templates; you need to explicitly re-import macros in each file.

Tip

To import macros from the current file, use the special _self variable:

1
2
3
{% import _self as forms %}

<p>{{ forms.input('username') }}</p>

When you define a macro in the template where you are going to use it, you might be tempted to call the macro directly via _self.input() instead of importing it; even if it seems to work, this is just a side-effect of the current implementation and it won't work anymore in Twig 2.x.

Named Macro End-Tags

Twig allows you to put the name of the macro after the end tag for better readability (the name after the endmacro word must match the macro name):

1
2
3
{% macro input() %}
    ...
{% endmacro input %}
« include | sandbox »