a SensioLabs Product

The flexible, fast, and secure
template engine for PHP

Tags » use

Questions & Feedback

License

Twig documentation is licensed under the new BSD license.

useΒΆ

New in version 1.1: Horizontal reuse was added in Twig 1.1.

Note

Horizontal reuse is an advanced Twig feature that is hardly ever needed in regular templates. It is mainly used by projects that need to make template blocks reusable without using inheritance.

Template inheritance is one of the most powerful Twig's feature but it is limited to single inheritance; a template can only extend one other template. This limitation makes template inheritance simple to understand and easy to debug:

1
2
3
4
{% extends "base.html" %}

{% block title %}{% endblock %}
{% block content %}{% endblock %}

Horizontal reuse is a way to achieve the same goal as multiple inheritance, but without the associated complexity:

1
2
3
4
5
6
{% extends "base.html" %}

{% use "blocks.html" %}

{% block title %}{% endblock %}
{% block content %}{% endblock %}

The use statement tells Twig to import the blocks defined in blocks.html into the current template (it's like macros, but for blocks):

1
2
3
{# blocks.html #}

{% block sidebar %}{% endblock %}

In this example, the use statement imports the sidebar block into the main template. The code is mostly equivalent to the following one (the imported blocks are not outputted automatically):

1
2
3
4
5
{% extends "base.html" %}

{% block sidebar %}{% endblock %}
{% block title %}{% endblock %}
{% block content %}{% endblock %}

Note

The use tag only imports a template if it does not extend another template, if it does not define macros, and if the body is empty. But it can use other templates.

Note

Because use statements are resolved independently of the context passed to the template, the template reference cannot be an expression.

The main template can also override any imported block. If the template already defines the sidebar block, then the one defined in blocks.html is ignored. To avoid name conflicts, you can rename imported blocks:

1
2
3
4
5
6
7
{% extends "base.html" %}

{% use "blocks.html" with sidebar as base_sidebar, title as base_title %}

{% block sidebar %}{% endblock %}
{% block title %}{% endblock %}
{% block content %}{% endblock %}

New in version 1.3: The parent() support was added in Twig 1.3.

The parent() function automatically determines the correct inheritance tree, so it can be used when overriding a block defined in an imported template:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{% extends "base.html" %}

{% use "blocks.html" %}

{% block sidebar %}
    {{ parent() }}
{% endblock %}

{% block title %}{% endblock %}
{% block content %}{% endblock %}

In this example, parent() will correctly call the sidebar block from the blocks.html template.

Tip

In Twig 1.2, renaming allows you to simulate inheritance by calling the "parent" block:

1
2
3
4
5
6
7
{% extends "base.html" %}

{% use "blocks.html" with sidebar as parent_sidebar %}

{% block sidebar %}
    {{ block('parent_sidebar') }}
{% endblock %}

Note

You can use as many use statements as you want in any given template. If two imported templates define the same block, the latest one wins.

This website is powered by PHP and Twig. The Twig logo is © 2010-2016 SensioLabs