include_only

Returned Value

The returned content is a \Twig\Markup instance, so it is considered safe and is not escaped again when you store it in a variable and print it later:

1
2

{% set body = include_only('body.html.twig') %}
{{ body }} {# rendered as-is, not re-escaped #}

Beware that, like any safe value, it is not re-escaped for the context it ends up in, so only embed it in the same context it was rendered for (typically HTML).

Passing Variables

As the context is not passed, variables a template needs must be passed explicitly:

1
2

{# template.html.twig will only have access to the "name" variable #}
{{ include_only('template.html.twig', {name: 'Fabien'}) }}

When passing a variable from the current context, you can use the following shortcut:

1
2
3
4
5

{{ include_only('template.html.twig', {name, email}) }}

{# is equivalent to #}

{{ include_only('template.html.twig', {name: name, email: email}) }}

Loading Templates

If you are using the filesystem loader, the templates are looked for in the paths defined by it.

If the expression evaluates to a \Twig\TemplateWrapper instance, Twig will use it directly:

1
2
3
4
5

// {{ include_only(template) }}

$template = $twig->load('some_template.html.twig');

$twig->display('template.html.twig', ['template' => $template]);

When you set the ignore_missing flag, Twig will return an empty string if the template does not exist:

1

{{ include_only('sidebar.html.twig', ignore_missing: true) }}

You can also provide a list of templates that are checked for existence before inclusion. The first template that exists will be rendered:

1

{{ include_only(['page_detailed.html.twig', 'page.html.twig']) }}

If ignore_missing is set, it will fall back to rendering nothing if none of the templates exist, otherwise it will throw an exception.

To render a template created by an end user, use the render_sandboxed() function.

Arguments

• template: The template to render
• variables: The variables to pass to the template
• ignore_missing: Whether to ignore missing templates or not