include, embed and macros – when to use which for reuse?

[mpdude]

This is a question my frontend guys ask me quite often and to be honest, I don't have a good one-size-fits-all answer. Unfortunately, the docs aren't helpful either.

So, the following blocks of code roughly do the same:

include

# someFile.html.twig
{% set foo = "Foo!" %}
{% set bar %} {# <-- omit this assignment if you want the default #}
   even more bar
{% endset %}
{% include "reused.html.twig" %}

# reused.html.twig
<h1>{{ foo }} </h1>
<p>Some common stuff.</p>
{% if bar %}
    {{ bar | raw }} 
{% else %}
    <p>Default text for bar.</p>
{% endif %}

embed

# someFile.html.twig
{% embed "reused.html.twig" %}
    {% block foo %} Foo! {% endblock %}
    {% block bar %} {# <-- again, this may be omitted #}
       even more bar
    {% endblock %}
{% endembed %}

# reused.html.twig
<h1>{% block foo %}{% endblock %} </h1>
<p>Some common stuff.</p>
{% block bar %}
    <p>Default text for bar.</p>
{% endblock %}

macro

# someFile.html.twig
{% import "reused.html.twig" as macros %}
{% set bar %} {# <-- omit this assignment if you want the default #}
   even more bar
{% endset %}
{{ macros.someBlock("Foo!", bar) }}

# reused.html.twig
{% macro someBlock(foo, bar) %}
<h1>{{ foo }} </h1>
<p>Some common stuff.</p>
{% if bar %}
    {{ bar | raw }} 
{% else %}
    <p>Default text for bar.</p>
{% endif %}
{% endmacro %}

There are many pros and cons for all of those approaches, including readablility, conciseness or the benefits of having an explicit interface (macro signature) and the benefits of encapsulation/scoping variables.

Are there any recommendations or is there a good rule of thumb when to use which?

Needless to say I'd be glad to write the doc PR if we get a good result here :-).

[stof]

Regarding include vs embed, the choice between them is easy: if you need to overwrite some blocks of the included template, use embed (this is the goal of this tag). If you don't need to overwrite blocks, use include. It will do the same in a faster way.

Regarding the scoping of variables, this is also possible with include or embed: http://twig.sensiolabs.org/doc/tags/include.html

Regarding the use case for macros, I will let other answer, as I actually don't use them much.

[fabpot]

Macros: reusable markup across a lot of templates
Includes: part of "pages" that are extracted for readability and reusability
Embed: @stof explained when it's useful (block overriding)

[Jero786]

I think this is a interesting blog about macros/includes using component approach.