Creating and Using Templates

Twig Configuration

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

Template Naming

Symfony recommends the following for template names:

• Use snake case for filenames and directories (e.g. blog_posts.html.twig, admin/default_theme/blog/index.html.twig, etc.);
• Define two extensions for filenames (e.g. index.html.twig or blog_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 any text-based format. That's why the two-extension convention simplifies the way templates are created and rendered for multiple formats.

Template Location

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

The default templates directory is configurable with the twig.default_path option and you can add more template directories as explained later in this article.

Template Variables

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

1

<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 variable in the following order:

1. $foo['bar'] (array and element);
2. $foo->bar (object and public property);
3. $foo->bar() (object and public method);
4. $foo->getBar() (object and getter method);
5. $foo->isBar() (object and isser method);
6. $foo->hasBar() (object and hasser method);
7. If none of the above exists, use null (or throw a Twig\Error\RuntimeError exception if the strict_variables option is enabled).

This allows to evolve your application code without having to change the template code (you can start with array variables for the application proof of concept, then move to objects with methods, etc.)

Linking to Pages

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

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

Consider the following routing configuration:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

// src/Controller/BlogController.php
namespace App\Controller;

// ...
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

class BlogController extends AbstractController
{
    #[Route('/', name: 'blog_index')]
    public function index(): Response
    {
        // ...
    }

    #[Route('/article/{slug}', name: 'blog_post')]
    public function show(string $slug): Response
    {
        // ...
    }
}

1
2
3
4
5
6
7
8

# config/routes.yaml
blog_index:
    path:       /
    controller: App\Controller\BlogController::index

blog_post:
    path:       /article/{slug}
    controller: App\Controller\BlogController::show

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<!-- 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>

1
2
3
4
5
6
7
8
9
10
11
12
13

// config/routes.php
use App\Controller\BlogController;
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;

return function (RoutingConfigurator $routes): void {
    $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 name as the first argument and the route parameters as the optional second argument:

1
2
3
4
5
6
7
8
9
10
11

<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 generate absolute 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 provides an asset() Twig function to help generate that URL. First, install the asset package:

1

$ composer require symfony/asset

You can now use the asset() function:

1
2
3
4
5
6
7
8

{# 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 application lives in a subdirectory (e.g. https://example.com/my_app), each asset path should render with the subdirectory (e.g. /my_app/images/logo.png). The asset() function takes care of this by determining how your application is being used and generating the correct paths accordingly.

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

1
2
3

<img src="{{ absolute_url(asset('images/logo.png')) }}" alt="Symfony!"/>

<link rel="shortcut icon" href="{{ absolute_url('favicon.png') }}">

Build, Versioning & More Advanced CSS, JavaScript and Image Handling

For help building and versioning your JavaScript and CSS assets in a modern way, read about Symfony's AssetMapper.

The App Global Variable

Symfony creates a context object that is injected into every Twig template automatically as a variable called app. It provides access to some application information:

1
2
3
4
5

<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 user is not authenticated.

app.request

The Request object that stores the current request data (depending on your application, this can be a sub-request or a regular request).

app.session

The Session object that represents 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 TokenInterface object representing the security token.

app.current_route

The name of the route associated with the current request or null if no request is available (equivalent to app.request.attributes.get('_route'))

app.current_route_parameters

An array with the parameters passed to the route of the current request or an empty array if no request is available (equivalent to app.request.attributes.get('_route_params'))

app.locale

The locale used in the current locale switcher context.

app.enabled_locales

The locales enabled in the application.

In addition to the global app variable injected by Symfony, you can also inject variables automatically to all Twig templates as explained in the next section.

Global Variables

Twig allows you to automatically inject one or more variables into all templates. These global variables are defined in the twig.globals option inside the main Twig configuration file:

1
2
3
4
5

# config/packages/twig.yaml
twig:
    # ...
    globals:
        ga_tracking: 'UA-xxxxx-x'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<!-- config/packages/twig.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: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:global key="ga_tracking">UA-xxxxx-x</twig:global>
    </twig:config>
</container>

1
2
3
4
5
6
7
8

// config/packages/twig.php
use Symfony\Config\TwigConfig;

return static function (TwigConfig $twig): void {
    // ...

    $twig->global('ga_tracking')->value('UA-xxxxx-x');
};

Now, the variable ga_tracking is available in all Twig templates, so you can use it without having to pass it explicitly from the controller or service that renders the template:

1

<p>The Google tracking code is: {{ ga_tracking }}</p>

In addition to static values, Twig global variables can also reference services from the service container. The main drawback is that these services are not loaded lazily. In other words, as soon as Twig is loaded, your service is instantiated, even if you never use that global variable.

To define a service as a global Twig variable, prefix the service ID string with the @ character, which is the usual syntax to refer to services in container parameters:

1
2
3
4
5
6

# config/packages/twig.yaml
twig:
    # ...
    globals:
        # the value is the service's id
        uuid: '@App\Generator\UuidGenerator'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<!-- config/packages/twig.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: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:global key="uuid" id="App\Generator\UuidGenerator" type="service"/>
    </twig:config>
</container>

1
2
3
4
5
6
7
8
9

// config/packages/twig.php
use function Symfony\Component\DependencyInjection\Loader\Configurator\service;
use Symfony\Config\TwigConfig;

return static function (TwigConfig $twig): void {
    // ...

    $twig->global('uuid')->value(service('App\Generator\UuidGenerator'));
};

Now you can use the uuid variable in any Twig template to access to the UuidGenerator service:

1

UUID: {{ uuid.generate }}

Rendering a Template in Controllers

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

// src/Controller/ProductController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;

class ProductController extends AbstractController
{
    public function index(): Response
    {
        // ...

        // the `render()` method returns a `Response` object with the
        // contents created by the template
        return $this->render('product/index.html.twig', [
            'category' => '...',
            'promotions' => ['...', '...'],
        ]);

        // the `renderView()` method only returns the contents created by the
        // template, so you can use those contents later in a `Response` object
        $contents = $this->renderView('product/index.html.twig', [
            'category' => '...',
            'promotions' => ['...', '...'],
        ]);

        return new Response($contents);
    }
}

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

Another option is to use the #[Template] attribute on the controller method to define the template to render:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// src/Controller/ProductController.php
namespace App\Controller;

use Symfony\Bridge\Twig\Attribute\Template;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;

class ProductController extends AbstractController
{
    #[Template('product/index.html.twig')]
    public function index(): array
    {
        // ...

        // when using the #[Template] attribute, you only need to return
        // an array with the parameters to pass to the template (the attribute
        // is the one which will create and return the Response object).
        return [
            'category' => '...',
            'promotions' => ['...', '...'],
        ];
    }
}

The base AbstractController also provides the renderBlock() and renderBlockView() methods:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

// src/Controller/ProductController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;

class ProductController extends AbstractController
{
    // ...

    public function price(): Response
    {
        // ...

        // the `renderBlock()` method returns a `Response` object with the
        // block contents
        return $this->renderBlock('product/index.html.twig', 'price_block', [
            // ...
        ]);

        // the `renderBlockView()` method only returns the contents created by the
        // template block, so you can use those contents later in a `Response` object
        $contents = $this->renderBlockView('product/index.html.twig', 'price_block', [
            // ...
        ]);

        return new Response($contents);
    }
}

This might come handy when dealing with blocks in templates inheritance or when using Turbo Streams.

Rendering a Template in Services

Inject the twig Symfony service into your own services and use its render() method. When using service autowiring you only need to add an argument in the service constructor and type-hint it with the Twig Environment:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

// src/Service/SomeService.php
namespace App\Service;

use Twig\Environment;

class SomeService
{
    public function __construct(
        private Environment $twig,
    ) {
    }

    public function someMethod(): void
    {
        // ...

        $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 can render static pages that don't need any variables directly from the route definition. Use the special TemplateController provided by Symfony:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

# 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'

        # the response status code (default: 200)
        statusCode: 200

        # special options defined by Symfony to set the page cache
        maxAge:    86400
        sharedAge: 86400

        # whether or not caching should apply for client caches only
        private: true

        # optionally you can define some arguments passed to the template
        context:
            site_name: 'ACME'
            theme: 'dark'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

<!-- 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>

        <!-- the response status code (default: 200) -->
        <default key="statusCode">200</default>

        <!-- special options defined by Symfony to set the page cache -->
        <default key="maxAge">86400</default>
        <default key="sharedAge">86400</default>

        <!-- whether or not caching should apply for client caches only -->
        <default key="private">true</default>

        <!-- optionally you can define some arguments passed to the template -->
        <default key="context">
            <default key="site_name">ACME</default>
            <default key="theme">dark</default>
        </default>
    </route>
</routes>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

// config/routes.php
use Symfony\Bundle\FrameworkBundle\Controller\TemplateController;
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;

return function (RoutingConfigurator $routes): void {
    $routes->add('acme_privacy', '/privacy')
        ->controller(TemplateController::class)
        ->defaults([
            // the path of the template to render
            'template'  => 'static/privacy.html.twig',

            // the response status code (default: 200)
            'statusCode' => 200,

            // special options defined by Symfony to set the page cache
            'maxAge'    => 86400,
            'sharedAge' => 86400,

            // whether or not caching should apply for client caches only
            'private' => true,

            // optionally you can define some arguments passed to the template
            'context' => [
                'site_name' => 'ACME',
                'theme' => 'dark',
            ]
        ])
    ;
};

Checking if a Template Exists

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

1
2
3
4
5
6
7
8
9
10
11

use Twig\Environment;

class YourService
{
    // this code assumes that your service uses autowiring to inject dependencies
    // otherwise, inject the service called 'twig' manually
    public function __construct(Environment $twig)
    {
        $loader = $twig->getLoader();
    }
}

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

1
2
3
4

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

Linting Twig Templates

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

1
2
3
4
5
6
7
8
9

# check all the application templates
$ php bin/console lint:twig

# you can also check directories and individual templates
$ php bin/console lint:twig templates/email/
$ php bin/console lint:twig templates/article/recent_list.html.twig

# you can also show the deprecated features used in your templates
$ php bin/console lint:twig --show-deprecations templates/email/

When running the linter inside GitHub Actions, the output is automatically adapted to the format required by GitHub, but you can force that format too:

1

$ php bin/console lint:twig --format=github

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 your custom Twig extensions are working properly and also to check the Twig features added when installing packages:

1
2
3
4
5
6
7
8

# 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 an improved alternative to PHP's var_dump() function. This function is useful to 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:

1

$ composer require --dev symfony/debug-bundle

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

{# 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) }}

    {# optionally, use named arguments to display them as labels next to
       the dumped contents #}
    {{ dump(blog_posts: articles, user: app.user) }}

    <a href="/article/{{ article.slug }}">
        {{ article.title }}
    </a>
{% endfor %}

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

Including Templates

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

1
2
3
4
5
6
7

{# templates/blog/index.html.twig #}

{# ... #}
<div class="user-profile">
    <img src="{{ user.profileImageUrl }}" alt="{{ user.fullName }}"/>
    <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 differentiate between full templates and template fragments).

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

1
2
3
4

{# templates/blog/index.html.twig #}

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

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

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

1
2
3
4

{# templates/blog/index.html.twig #}

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

Embedding Controllers

Including template fragments is useful to reuse the same content on several pages. However, this technique is not the best solution in 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 using the include() function, you'd need to do the same database query in every page that includes the fragment. This is not very convenient.

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// src/Controller/BlogController.php
namespace App\Controller;

use Symfony\Component\HttpFoundation\Response;
// ...

class BlogController extends AbstractController
{
    public function recentArticles(int $max = 3): Response
    {
        // 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 to better differentiate between full templates and template fragments):

1
2
3
4
5
6

{# 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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{# 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 a regular Symfony route but through a special URL used exclusively to serve those template fragments. Configure that special URL in the fragments option:

1
2
3
4

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14

<!-- 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>

1
2
3
4
5
6
7

// config/packages/framework.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework): void {
    // ...
    $framework->fragments()->path('/_fragment');
};

Template Inheritance and Layouts

As your application grows you'll find more and more repeated elements between pages, such as headers, footers, sidebars, etc. Including templates and embedding controllers can help, but when 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 child templates can override parts of the parent template.

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

• templates/base.html.twig, defines the common elements of all application templates, such as <head>, <header>, <footer>, etc.;
• templates/layout.html.twig, extends from base.html.twig and defines the content structure used in all or most of the pages, such as a two-column content + sidebar layout. Some sections of the application can define their own layouts (e.g. templates/blog/layout.html.twig);
• templates/*.html.twig, the application pages which extend from the main layout.html.twig template or any other section layout.

In practice, the base.html.twig template would look like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

{# templates/base.html.twig #}
<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8">
        <title>{% block title %}My Application{% endblock %}</title>
        {% block stylesheets %}
            <link rel="stylesheet" type="text/css" href="/css/base.css"/>
        {% endblock %}
    </head>
    <body>
        {% block 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 content %}{% endblock %}
            </div>
        {% endblock %}
    </body>
</html>

The Twig block tag defines the page sections that can be overridden in the child templates. They can be empty, like the content block or define a default content, like the title block, which is displayed when child templates don't override them.

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

1
2
3
4
5
6
7
8

{# templates/blog/layout.html.twig #}
{% extends 'base.html.twig' %}

{% block content %}
    <h1>Blog</h1>

    {% block page_contents %}{% endblock %}
{% endblock %}

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

1
2
3
4
5
6
7
8
9
10
11

{# templates/blog/index.html.twig #}
{% extends 'blog/layout.html.twig' %}

{% block title %}Blog Index{% endblock %}

{% block page_contents %}
    {% 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: page_contents from blog/layout.html.twig and title from base.html.twig.

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

1
2
3
4
5
6
7
8

{# templates/blog/index.html.twig #}
{% extends 'base.html.twig' %}

{# the line below is not captured by a "block" tag #}
<div class="alert">Some Alert</div>

{# the following is valid #}
{% block content %}My cool blog posts{% endblock %}

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

Bundle Templates

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

For example, the templates of a bundle called AcmeBlogBundle are available under the AcmeBlog namespace. If this bundle includes the template <your-project>/vendor/acme/blog-bundle/templates/user/profile.html.twig, you can refer to it as @AcmeBlog/user/profile.html.twig.

Create the Extension Class

Suppose you want to create a new filter called price that formats a number as currency:

1
2
3
4

{{ product.price|price }}

{# pass in the 3 optional arguments #}
{{ product.price|price(2, ',', '.') }}

Create a class that extends AbstractExtension and fill in the logic:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// src/Twig/AppExtension.php
namespace App\Twig;

use Twig\Extension\AbstractExtension;
use Twig\TwigFilter;

class AppExtension extends AbstractExtension
{
    public function getFilters(): array
    {
        return [
            new TwigFilter('price', [$this, 'formatPrice']),
        ];
    }

    public function formatPrice(float $number, int $decimals = 0, string $decPoint = '.', string $thousandsSep = ','): string
    {
        $price = number_format($number, $decimals, $decPoint, $thousandsSep);
        $price = '$'.$price;

        return $price;
    }
}

If you want to create a function instead of a filter, define the getFunctions() method:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// src/Twig/AppExtension.php
namespace App\Twig;

use Twig\Extension\AbstractExtension;
use Twig\TwigFunction;

class AppExtension extends AbstractExtension
{
    public function getFunctions(): array
    {
        return [
            new TwigFunction('area', [$this, 'calculateArea']),
        ];
    }

    public function calculateArea(int $width, int $length): int
    {
        return $width * $length;
    }
}

1
2
3
4
5

# display all information about Twig
$ php bin/console debug:twig

# display only the information about a specific filter
$ php bin/console debug:twig --filter=price

Creating Lazy-Loaded Twig Extensions

Including the code of the custom filters/functions in the Twig extension class is the simplest way to create extensions. However, Twig must initialize all extensions before rendering any template, even if the template doesn't use an extension.

If extensions don't define dependencies (i.e. if you don't inject services in them) performance is not affected. However, if extensions define lots of complex dependencies (e.g. those making database connections), the performance loss can be significant.

That's why Twig allows decoupling the extension definition from its implementation. Following the same example as before, the first change would be to remove the formatPrice() method from the extension and update the PHP callable defined in getFilters():

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// src/Twig/AppExtension.php
namespace App\Twig;

use App\Twig\AppRuntime;
use Twig\Extension\AbstractExtension;
use Twig\TwigFilter;

class AppExtension extends AbstractExtension
{
    public function getFilters(): array
    {
        return [
            // the logic of this filter is now implemented in a different class
            new TwigFilter('price', [AppRuntime::class, 'formatPrice']),
        ];
    }
}

Then, create the new AppRuntime class (it's not required but these classes are suffixed with Runtime by convention) and include the logic of the previous formatPrice() method:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

// src/Twig/AppRuntime.php
namespace App\Twig;

use Twig\Extension\RuntimeExtensionInterface;

class AppRuntime implements RuntimeExtensionInterface
{
    public function __construct()
    {
        // this simple example doesn't define any dependency, but in your own
        // extensions, you'll need to inject services using this constructor
    }

    public function formatPrice(float $number, int $decimals = 0, string $decPoint = '.', string $thousandsSep = ','): string
    {
        $price = number_format($number, $decimals, $decPoint, $thousandsSep);
        $price = '$'.$price;

        return $price;
    }
}

If you're using the default services.yaml configuration, this will already work! Otherwise, create a service for this class and tag your service with twig.runtime.