Macros are one of the most important features of the Twig template language to avoid repetitive contents. In Twig 2.11, usage of macros was simplified and other features were added to help you work with macros.

Automatic macro import¶

Macros are similar to PHP functions because you can pass arguments to them and the contents generated inside the macro are returned to include them in the place where the macro is called.

On symfony.com we use macros for example to display the "contributor box" in several places to highlight our amazing Symfony code and docs contributors:

1 2 3 4 5 6 {% macro contributor_details ( contributor , vertical_layout = false ) %} <div class="d-flex"> <img class="avatar {{ vertical_layout ? 'm-b-15' }} " src="..."> Thanks {{ contributor.name }} for being a Symfony contributor. </div> {% endmacro %}

Before calling to a macro in a template you must import it, even if the macro is defined in the same template. This behavior always felt confusing to some people and made using macros a bit annoying. Starting from Twig 2.11, we've fixed that and macros defined in the same template are imported automatically under the special variable _self :

1 2 3 4 5 6 7 8 9 10 11 12 13 14 {# templates/some-template.html.twig #} {% macro contributor_details ( contributor , vertical_layout = false ) %} <div class="d-flex"> <img class="avatar {{ vertical_layout ? 'm-b-15' }} " src="..."> Thanks {{ contributor.name }} for being a Symfony contributor. </div> {% endmacro %} {# ... #} {% for contributor in contributors %} {# you don't have to import the macro before using it #} {{ _self.contributor_details ( contributor ) }} {% endfor %}

This automatic import also works for macros themselves, so you can call to a macro inside another macro of the same template without importing it explicitly (this also works for any macro imported globally in the template):