Creating and Using Templates

Creating and Using Templates

A template is the best way to organize and render HTML from inside your application,whether you need to render HTML from a controller or generatethe contents of an email. Templates in Symfony are created withTwig: a flexible, fast, and secure template engine.

Twig Templating Language

The Twig templating language allows you to write concise, readable templatesthat are more friendly to web designers and, in several ways, more powerful thanPHP templates. Take a look at the following Twig template example. Even if it'sthe first time you see Twig, you probably understand most of it:

<!DOCTYPE html>
<html>
    <head>
        <title>Welcome to Symfony!</title>
    </head>
    <body>
        <h1>{{ page_title }}</h1>
 
        {% if user.isLoggedIn %}
            Hello {{ user.name }}!
        {% endif %}
 
        {# ... #}
    </body>
</html>

Twig syntax is based on these three constructs:

{{ … }}, used to display the content of a variable or the result ofevaluating an expression;
{% … %}, used to run some logic, such as a conditional or a loop;
{# … #}, used to add comments to the template (unlike HTML comments,these comments are not included in the rendered page).You can't run PHP code inside Twig templates, but Twig provides utilities torun some logic in the templates. For example, filters modify content beforebeing rendered, like the upper filter to uppercase contents:

{{ title|upper }}

Twig comes with a long list of tags, filters and functions that areavailable by default. In Symfony applications you can also use theseTwig filters and functions defined by Symfonyand you can create your own Twig filters and functions.

Twig is fast in the prod environment(because templates are compiled into PHP and cached automatically), butconvenient to use in the dev environment (because templates are recompiledautomatically when you change them).

Twig Configuration

Twig has several configuration options to define things like the format usedto display numbers and dates, the template caching, etc. Read theTwig configuration reference to learn about them.

Creating Templates

Before explaining in detail how to create and render templates, look at thefollowing example for a quick overview of the whole process. First, you need tocreate a new file in the templates/ directory to store the template contents:

{# templates/user/notifications.html.twig #}
<h1>Hello {{ user_first_name }}!</h1>
<p>You have {{ notifications|length }} new notifications.</p>

Then, create a controller that renders this template andpasses to it the needed variables:

// src/Controller/UserController.php
namespace App\Controller;
 
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
 
class UserController extends AbstractController
{
    // ...
 
    public function notifications()
    {
        // get the user information and notifications somehow
        $userFirstName = '...';
        $userNotifications = ['...', '...'];
 
        // the template path is the relative file path from `templates/`
        return $this->render('user/notifications.html.twig', [
            // this array defines the variables passed to the template,
            // where the key is the variable name and the value is the variable value
            // (Twig recommends using snake_case variable names: 'foo_bar' instead of 'fooBar')
            'user_first_name' => $userFirstName,
            'notifications' => $userNotifications,
        ]);
    }
}

Template Naming

Symfony recommends the following for template names:

Use snake case for filenames and directories (e.g. blog_posts.twig,admin/default_theme/blog/index.twig, etc.);
Define two extensions for filenames (e.g. index.html.twig orblog_posts.xml.twig) being the first extension (html, xml, etc.)the final format that the template will generate.Although templates usually generate HTML contents, they can generate anytext-based format. That's why the two-extension convention simplifies the waytemplates are created and rendered for multiple formats.

Template Location

Templates are stored by default in the templates/ directory. When a serviceor controller renders the product/index.html.twig template, they are actuallyreferring to the <your-project>/templates/product/index.html.twig file.

The default templates directory is configurable with thetwig.default_path option and you can add moretemplate directories as explained later in this article.

Template Variables

A common need for templates is to print the values stored in the templatespassed from the controller or service. Variables usually store objects andarrays instead of strings, numbers and boolean values. That's why Twig providesquick access to complex PHP variables. Consider the following template:

<p>{{ user.name }} added this comment on {{ comment.publishedAt|date }}</p>

The user.name notation means that you want to display some information(name) stored in a variable (user). Is user an array or an object?Is name a property or a method? In Twig this doesn't matter.

When using the foo.bar notation, Twig tries to get the value of the variablein the following order:

$foo['bar'] (array and element);
$foo->bar (object and public property);
$foo->bar() (object and public method);
$foo->getBar() (object and getter method);
$foo->isBar() (object and isser method);
$foo->hasBar() (object and hasser method);
If none of the above exists, use null.This allows to evolve your application code without having to change thetemplate code (you can start with array variables for the application proof ofconcept, then move to objects with methods, etc.)

Linking to Pages

Instead of writing the link URLs by hand, use the path() function togenerate URLs based on the routing configuration.

Later, if you want to modify the URL of a particular page, all you'll need to dois change the routing configuration: the templates will automatically generatethe new URL.

Consider the following routing configuration:

Annotations

// src/Controller/BlogController.php
 
// ...
use Symfony\Component\Routing\Annotation\Route;
 
class BlogController extends AbstractController
{
    /**
     * @Route("/", name="blog_index")
     */
    public function index()
    {
        // ...
    }
 
    /**
     * @Route("/article/{slug}", name="blog_post")
     */
    public function show(string $slug)
    {
        // ...
    }
}

YAML

# config/routes.yaml
blog_index:
    path:       /
    controller: App\Controller\BlogController::index
 
blog_post:
    path:       /article/{slug}
    controller: App\Controller\BlogController::show

XML

<!-- config/routes.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<routes xmlns="http://symfony.com/schema/routing"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/routing
        https://symfony.com/schema/routing/routing-1.0.xsd">
 
    <route id="blog_index"
        path="/"
        controller="App\Controller\BlogController::index"/>
 
    <route id="blog_post"
        path="/article/{slug}"
        controller="App\Controller\BlogController::show"/>
</routes>

PHP

// config/routes.php
use App\Controller\BlogController;
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
 
return function (RoutingConfigurator $routes) {
    $routes->add('blog_index', '/')
        ->controller([BlogController::class, 'index'])
    ;
 
    $routes->add('blog_post', '/articles/{slug}')
        ->controller([BlogController::class, 'show'])
    ;
};

Use the path() Twig function to link to these pages and pass the route nameas the first argument and the route parameters as the optional second argument:

<a href="{{ path('blog_index') }}">Homepage</a>
 
{# ... #}
 
{% for post in blog_posts %}
    <h1>
        <a href="{{ path('blog_post', {slug: post.slug}) }}">{{ post.title }}</a>
    </h1>
 
    <p>{{ post.excerpt }}</p>
{% endfor %}

The path() function generates relative URLs. If you need to generateabsolute URLs (for example when rendering templates for emails or RSS feeds),use the url() function, which takes the same arguments as path()(e.g. <a href="{{ url('blog_index') }}"> … </a>).

Linking to CSS, JavaScript and Image Assets

If a template needs to link to a static asset (e.g. an image), Symfony providesan asset() Twig function to help generate that URL. First, install theasset package:

$ composer require symfony/asset

You can now use the asset() function:

{# the image lives at "public/images/logo.png" #}
<img src="{{ asset('images/logo.png') }}" alt="Symfony!"/>
 
{# the CSS file lives at "public/css/blog.css" #}
<link href="{{ asset('css/blog.css') }}" rel="stylesheet"/>
 
{# the JS file lives at "public/bundles/acme/js/loader.js" #}
<script src="{{ asset('bundles/acme/js/loader.js') }}"></script>

The asset() function's main purpose is to make your application more portable.If your application lives at the root of your host (e.g. https://example.com),then the rendered path should be /images/logo.png. But if your applicationlives in a subdirectory (e.g. https://example.com/my_app), each asset pathshould render with the subdirectory (e.g. /my_app/images/logo.png). Theasset() function takes care of this by determining how your application isbeing used and generating the correct paths accordingly.

Tip

The asset() function supports various cache busting techniques via theversion,version_format, andjson_manifest_path configuration options.

Tip

If you'd like help packaging, versioning and minifying your JavaScript andCSS assets in a modern way, read about Symfony's Webpack Encore.

If you need absolute URLs for assets, use the absolute_url() Twig functionas follows:

<img src="{{ absolute_url(asset('images/logo.png')) }}" alt="Symfony!"/>
 
<link rel="shortcut icon" href="{{ absolute_url('favicon.png') }}">

The App Global Variable

Symfony creates a context object that is injected into every Twig templateautomatically as a variable called app. It provides access to someapplication information:

<p>Username: {{ app.user.username ?? 'Anonymous user' }}</p>
{% if app.debug %}
    <p>Request method: {{ app.request.method }}</p>
    <p>Application Environment: {{ app.environment }}</p>
{% endif %}

The app variable (which is an instance of AppVariable)gives you access to these variables:

app.user
The current user object or null if the useris not authenticated.
app.request
The Request object that storesthe current request data (depending on yourapplication, this can be a sub-requestor a regular request).
app.session
The Session object thatrepresents the current user's session or null if there is none.
app.flashes
An array of all the flash messages stored in the session.You can also get only the messages of some type (e.g. app.flashes('notice')).
app.environment
The name of the current configuration environment(dev, prod, etc).
app.debug
True if in debug mode. False otherwise.
app.token
A TokenInterfaceobject representing the security token.In addition to the global app variable injected by Symfony, you can alsoinject variables automatically to all Twig templates.

Rendering Templates

Rendering a Template in Controllers

If your controller extends from the AbstractController,use the render() helper:

// src/Controller/ProductController.php
namespace App\Controller;
 
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
 
class ProductController extends AbstractController
{
    public function index()
    {
        // ...
 
        return $this->render('product/index.html.twig', [
            'category' => '...',
            'promotions' => ['...', '...'],
        ]);
    }
}

If your controller does not extend from AbstractController, you'll need tofetch services in your controller anduse the render() method of the twig service.

Rendering a Template in Services

Inject the twig Symfony service into your own services and use itsrender() method. When using service autowiringyou only need to add an argument in the service constructor and type-hint it withthe Environment class:

// src/Service/SomeService.php
use Twig\Environment;
 
class SomeService
{
    private $twig;
 
    public function __construct(Environment $twig)
    {
        $this->twig = $twig;
    }
 
    public function someMethod()
    {
        // ...
 
        $htmlContents = $this->twig->render('product/index.html.twig', [
            'category' => '...',
            'promotions' => ['...', '...'],
        ]);
    }
}

Rendering a Template in Emails

Read the docs about the mailer and Twig integration.

Rendering a Template Directly from a Route

Although templates are usually rendered in controllers and services, you canrender static pages that don't need any variables directly from the routedefinition. Use the special TemplateController provided by Symfony:

YAML

# config/routes.yaml
acme_privacy:
    path:          /privacy
    controller:    Symfony\Bundle\FrameworkBundle\Controller\TemplateController
    defaults:
        # the path of the template to render
        template:  'static/privacy.html.twig'
 
        # special options defined by Symfony to set the page cache
        maxAge:    86400
        sharedAge: 86400
 
        # optionally you can define some arguments passed to the template
        site_name: 'ACME'
        theme: 'dark'

XML

<!-- config/routes.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<routes xmlns="http://symfony.com/schema/routing"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/routing https://symfony.com/schema/routing/routing-1.0.xsd">
 
    <route id="acme_privacy"
        path="/privacy"
        controller="Symfony\Bundle\FrameworkBundle\Controller\TemplateController">
        <!-- the path of the template to render -->
        <default key="template">static/privacy.html.twig</default>
 
        <!-- special options defined by Symfony to set the page cache -->
        <default key="maxAge">86400</default>
        <default key="sharedAge">86400</default>
 
        <!-- optionally you can define some arguments passed to the template -->
        <default key="site_name">ACME</default>
        <default key="theme">dark</default>
    </route>
</routes>

PHP

// config/routes.php
use Symfony\Bundle\FrameworkBundle\Controller\TemplateController;
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
 
return function (RoutingConfigurator $routes) {
    $routes->add('acme_privacy', '/privacy')
        ->controller(TemplateController::class)
        ->defaults([
            // the path of the template to render
            'template'  => 'static/privacy.html.twig',
 
            // special options defined by Symfony to set the page cache
            'maxAge'    => 86400,
            'sharedAge' => 86400,
 
            // optionally you can define some arguments passed to the template
            'site_name' => 'ACME',
            'theme' => 'dark',
        ])
    ;
};

Checking if a Template Exists

Templates are loaded in the application using a Twig template loader, whichalso provides a method to check for template existence. First, get the loader:

// in a controller extending from AbstractController
$loader = $this->get('twig')->getLoader();
 
// in a service using autowiring
use Twig\Environment;
 
public function __construct(Environment $twig)
{
    $loader = $twig->getLoader();
}

Then, pass the path of the Twig template to the exists() method of the loader:

if ($loader->exists('theme/layout_responsive.html.twig')) {
    // the template exists, do something
    // ...
}

Debugging Templates

Symfony provides several utilities to help you debug issues in your templates.

Linting Twig Templates

The lint:twig command checks that your Twig templates don't have any syntaxerrors. It's useful to run it before deploying your application to production(e.g. in your continuous integration server):

# check all the templates stored in a directory
$ php bin/console lint:twig templates/
 
# you can also check individual templates
$ php bin/console lint:twig templates/article/recent_list.html.twig

Inspecting Twig Information

The debug:twig command lists all the information available about Twig(functions, filters, global variables, etc.). It's useful to check if yourcustom Twig extensions are working properlyand also to check the Twig features added when installing packages:

# list general information
$ php bin/console debug:twig
 
# filter output by any keyword
$ php bin/console debug:twig --filter=date
 
# pass a template path to show the physical file which will be loaded
$ php bin/console debug:twig @Twig/Exception/error.html.twig

The Dump Twig Utilities

Symfony provides a dump() function as animproved alternative to PHP's var_dump() function. This function is usefulto inspect the contents of any variable and you can use it in Twig templates too.

First, make sure that the VarDumper component is installed in the application:

$ composer require symfony/var-dumper

Then, use either the {% dump %} tag or the {{ dump() }} functiondepending on your needs:

{# templates/article/recent_list.html.twig #}
{# the contents of this variable are sent to the Web Debug Toolbar
   instead of dumping them inside the page contents #}
{% dump articles %}
 
{% for article in articles %}
    {# the contents of this variable are dumped inside the page contents
       and they are visible on the web page #}
    {{ dump(article) }}
 
    <a href="/article/{{ article.slug }}">
        {{ article.title }}
    </a>
{% endfor %}

To avoid leaking sensitive information, the dump() function/tag is onlyavailable in the dev and test configuration environments.If you try to use it in the prod environment, you will see a PHP error.

Reusing Template Contents

Including Templates

If certain Twig code is repeated in several templates, you can extract it into asingle "template fragment" and include it in other templates. Imagine that thefollowing code to display the user information is repeated in several places:

{# templates/blog/index.html.twig #}
 
{# ... #}
<div class="user-profile">
    <img src="{{ user.profileImageUrl }}"/>
    <p>{{ user.fullName }} - {{ user.email }}</p>
</div>

First, create a new Twig template called blog/user_profile.html.twig (the prefix is optional, but it's a convention used to better differentiatebetween full templates and template fragments).

Then, remove that content from the original blog/index.html.twig templateand add the following to include the template fragment:

{# templates/blog/index.html.twig #}
 
{# ... #}
{{ include('blog/_user_profile.html.twig') }}

The include() Twig function takes as argument the path of the template toinclude. The included template has access to all the variables of the templatethat includes it (use the with_context option to control this).

You can also pass variables to the included template. This is useful for exampleto rename variables. Imagine that your template stores the user information in avariable called blogpost.author instead of the user variable that thetemplate fragment expects. Use the following to _rename the variable:

{# templates/blog/index.html.twig #}
 
{# ... #}
{{ include('blog/_user_profile.html.twig', {user: blog_post.author}) }}

Embedding Controllers

Including template fragments is useful to reuse thesame content on several pages. However, this technique is not the best solutionin some cases.

Imagine that the template fragment displays the three most recent blog articles.To do that, it needs to make a database query to get those articles. When usingthe include() function, you'd need to do the same database query in everypage that includes the fragment. This is not very convenient.

A better alternative is to embed the result of executing some controllerwith the render() and controller() Twig functions.

First, create the controller that renders a certain number of recent articles:

// src/Controller/BlogController.php
namespace App\Controller;
 
// ...
 
class BlogController extends AbstractController
{
    public function recentArticles($max = 3)
    {
        // get the recent articles somehow (e.g. making a database query)
        $articles = ['...', '...', '...'];
 
        return $this->render('blog/_recent_articles.html.twig', [
            'articles' => $articles
        ]);
    }
}

Then, create the blog/recent_articles.html.twig template fragment (the prefix in the template name is optional, but it's a convention used tobetter differentiate between full templates and template fragments):

{# templates/blog/_recent_articles.html.twig #}
{% for article in articles %}
    <a href="{{ path('blog_show', {slug: article.slug}) }}">
        {{ article.title }}
    </a>
{% endfor %}

Now you can call to this controller from any template to embed its result:

{# templates/base.html.twig #}
 
{# ... #}
<div id="sidebar">
    {# if the controller is associated with a route, use the path() or url() functions #}
    {{ render(path('latest_articles', {max: 3})) }}
    {{ render(url('latest_articles', {max: 3})) }}
 
    {# if you don't want to expose the controller with a public URL,
       use the controller() function to define the controller to execute #}
    {{ render(controller(
        'App\\Controller\\BlogController::recentArticles', {max: 3}
    )) }}
</div>

When using the controller() function, controllers are not accessed using aregular Symfony route but through a special URL used exclusively to serve thosetemplate fragments. Configure that special URL in the fragments option:

YAML

# config/packages/framework.yaml
framework:
    # ...
    fragments: { path: /_fragment }

XML

<!-- config/packages/framework.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.com/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
    <!-- ... -->
    <framework:config>
        <framework:fragment path="/_fragment"/>
    </framework:config>
</container>

PHP

// config/packages/framework.php
$container->loadFromExtension('framework', [
    // ...
    'fragments' => ['path' => '/_fragment'],
]);

Caution

Embedding controllers require making requests to those controllers andrendering some templates as result. This can have a significant impact inthe application performance if you embed lots of controllers. If possible,cache the template fragment.

Templates can also embed contents asynchronouslywith the hinclude.js JavaScript library.

Template Inheritance and Layouts

As your application grows you'll find more and more repeated elements betweenpages, such as headers, footers, sidebars, etc. Including templatesand embedding controllers can help, butwhen pages share a common structure, it's better to use inheritance.

The concept of Twig template inheritance is similar to PHP class inheritance.You define a parent template that other templates can extend from and childtemplates can override parts of the parent template.

Symfony recommends the following three-level template inheritance for medium andcomplex applications:

templates/base.html.twig, defines the common elements of all applicationtemplates, such as <head>, <header>, <footer>, etc.;
templates/layout.html.twig, extends from base.html.twig and definesthe content structure used in all or most of the pages, such as a two-columncontent + sidebar layout. Some sections of the application can define theirown layouts (e.g. templates/blog/layout.html.twig);
templates/*.html.twig, the application pages which extend from the mainlayout.html.twig template or any other section layout.In practice, the base.html.twig template would look like this:

{# templates/base.html.twig #}
<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8">
        <title>{% block title %}My Application{% endblock %}</title>
    </head>
    <body>
        <div id="sidebar">
            {% block sidebar %}
                <ul>
                    <li><a href="{{ path('homepage') }}">Home</a></li>
                    <li><a href="{{ path('blog_index') }}">Blog</a></li>
                </ul>
            {% endblock %}
        </div>
 
        <div id="content">
            {% block body %}{% endblock %}
        </div>
    </body>
</html>

The Twig block tag defines the page sections that can be overridden in thechild templates. They can be empty, like the body block or define a defaultcontent, like the title block, which is displayed when child templates don'toverride them.

The blog/layout.html.twig template could be like this:

{# templates/blog/layout.html.twig #}
{% extends 'base.html.twig' %}
 
{% block body %}
    <h1>Blog</h1>
 
    {% block content %}{% endblock %}
{% endblock %}

The template extends from base.html.twig and only defines the contents ofthe body block. The rest of the parent template blocks will display theirdefault contents. However, they can be overridden by the third-level inheritancetemplate, such as blog/index.html.twig, which displays the blog index:

{# templates/blog/index.html.twig #}
{% extends 'blog/layout.html.twig' %}
 
{% block title %}Blog Index{% endblock %}
 
{% block content %}
    {% for article in articles %}
        <h2>{{ article.title }}</h2>
        <p>{{ article.body }}</p>
    {% endfor %}
{% endblock %}

This template extends from the second-level template (blog/layout.html.twig)but overrides blocks of different parent templates: content fromblog/index.html.twig and title from base.html.twig.

When you render the blog/index.html.twig template, Symfony uses threedifferent templates to create the final contents. This inheritance mechanismboosts your productivity because each template includes only its unique contentsand leaves the repeated contents and HTML structure to some parent templates.

Read the Twig template inheritance docs to learn more about how to reuseparent block contents when overriding templates and other advanced features.

Output Escaping

Imagine that your template includes the Hello {{ name }} code to display theuser name. If a malicious user sets <script>alert('hello!')</script> astheir name and you output that value unchanged, the application will display aJavaScript popup window.

This is known as a Cross-Site Scripting (XSS) attack. And while the previousexample seems harmless, the attacker could write more advanced JavaScript codeto performs malicious actions.

To prevent this attack, use "output escaping" to transform the characterswhich have special meaning (e.g. replace < by the < HTML entity).Symfony applications are safe by default because they perform automatic outputescaping thanks to the Twig autoescape option:

<p>Hello {{ name }}</p>
{# if 'name' is '<script>alert('hello!')</script>', Twig will output this:
   '<p>Hello &lt;script&gt;alert(&#39;hello!&#39;)&lt;/script&gt;</p>' #}

If you are rendering a variable that is trusted and contains HTML contents,use the Twig raw filter to disable the output escaping for that variable:

<h1>{{ product.title|raw }}</h1>
{# if 'product.title' is 'Lorem <strong>Ipsum</strong>', Twig will output
   exactly that instead of 'Lorem &lt;strong&gt;Ipsum&lt;/strong&gt;' #}

Read the Twig output escaping docs to learn more about how to disable outputescaping for a block or even an entire template.

Template Namespaces

Although most applications store their templates in the default templates/directory, you may need to store some or all of them in different directories.Use the twig.paths option to configure those extra directories. Each path isdefined as a key: value pair where the key is the template directory andthe value is the Twig namespace, which is explained later:

YAML

# config/packages/twig.yaml
twig:
    # ...
    paths:
        # directories are relative to the project root dir (but you
        # can also use absolute directories)
        'email/default/templates': ~
        'backend/templates': ~

XML

<!-- config/packages/twig.xml -->
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:twig="http://symfony.com/schema/dic/twig"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/twig https://symfony.com/schema/dic/twig/twig-1.0.xsd">
 
    <twig:config>
        <!-- ... -->
        <!-- directories are relative to the project root dir (but you
             can also use absolute directories -->
        <twig:path>email/default/templates</twig:path>
        <twig:path>backend/templates</twig:path>
    </twig:config>
</container>

PHP

// config/packages/twig.php
$container->loadFromExtension('twig', [
    // ...
    'paths' => [
        // directories are relative to the project root dir (but you
        // can also use absolute directories)
        'email/default/templates' => null,
        'backend/templates' => null,
    ],
]);

When rendering a template, Symfony looks for it first in the twig.pathsdirectories that don't define a namespace and then falls back to the defaulttemplate directory (usually, templates/).

Deprecated since version 4.2: Symfony looks for templates in the src/Resources/views/ too beforefalling back to the default directory. But that behavior is deprecated sinceSymfony 4.2 and will be removed in Symfony 5.0.

Using the above configuration, if your application renders for example thelayout.html.twig template, Symfony will first look foremail/default/templates/layout.html.twig and backend/templates/layout.html.twig.If any of those templates exists, Symfony will use it instead of usingtemplates/layout.html.twig, which is probably the template you wanted to use.

Twig solves this problem with namespaces, which group several templatesunder a logic name unrelated to their actual location. Update the previousconfiguration to define a namespace for each template directory:

YAML

# config/packages/twig.yaml
twig:
    # ...
    paths:
        'email/default/templates': 'email'
        'backend/templates': 'admin'

XML

<!-- config/packages/twig.xml -->
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:twig="http://symfony.com/schema/dic/twig"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/twig https://symfony.com/schema/dic/twig/twig-1.0.xsd">
 
    <twig:config>
        <!-- ... -->
        <twig:path namespace="email">email/default/templates</twig:path>
        <twig:path namespace="admin">backend/templates</twig:path>
    </twig:config>
</container>

PHP

// config/packages/twig.php
$container->loadFromExtension('twig', [
    // ...
    'paths' => [
        'email/default/templates' => 'email',
        'backend/templates' => 'admin',
    ],
]);

Now, if you render the layout.html.twig template, Symfony will render thetemplates/layout.html.twig file. Use the special syntax @ + namespace torefer to the other namespaced templates (e.g. @email/layout.html.twig and@admin/layout.html.twig).

Note

A single Twig namespace can be associated with more than one templatedirectory. In that case, the order in which paths are added is importantbecause Twig will start looking for templates from the first defined path.

Bundle Templates

If you install packages/bundles in your application, theymay include their own Twig templates (in the Resources/views/ directory ofeach bundle). To avoid messing with your own templates, Symfony adds bundletemplates under an automatic namespace created after the bundle name.

For example, the templates of a bundle called AcmeFooBundle are availableunder the AcmeFoo namespace. If this bundle includes the template<your-project>/vendor/acmefoo-bundle/Resources/views/user/profile.html.twig,you can refer to it as @AcmeFoo/user/profile.html.twig.

Tip

You can also override bundle templates in caseyou want to change some parts of the original bundle templates.

Templates