Symfony 4 was released on November 30th.
Update now to the best Symfony ever!

You are browsing the Symfony 4 documentation, which changes significantly from Symfony 3.x. If your app doesn't use Symfony 4 yet, browse the Symfony 3.4 documentation.

TwigBundle Configuration ("twig")

TwigBundle Configuration ("twig")

  • YAML
     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
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    # config/packages/twig.yaml
    twig:
        exception_controller:  twig.controller.exception:showAction
    
        form_themes:
    
            # Default:
            - form_div_layout.html.twig
    
            # Bootstrap:
            - bootstrap_3_layout.html.twig
            - bootstrap_3_horizontal_layout.html.twig
            - bootstrap_4_layout.html.twig
            - bootstrap_4_horizontal_layout.html.twig
    
            # Foundation
            - foundation_5_layout.html.twig
    
            # Example:
            - form.html.twig
    
        globals:
    
            # Examples:
            foo:                 '@bar'
            pi:                  3.14
    
            # Example options, but the easiest use is as seen above
            some_variable_name:
                # a service id that should be the value
                id:                   ~
                # set to service or leave blank
                type:                 ~
                value:                ~
        autoescape:                ~
    
        # See http://twig.sensiolabs.org/doc/recipes.html#using-the-template-name-to-set-the-default-escaping-strategy
        autoescape_service:        ~ # Example: 'my_service'
        autoescape_service_method: ~ # use in combination with autoescape_service option
        base_template_class:       ~ # Example: Twig_Template
        cache:                     '%kernel.cache_dir%/twig'
        charset:                   '%kernel.charset%'
        debug:                     '%kernel.debug%'
        strict_variables:          ~
        auto_reload:               ~
        optimizations:             ~
        default_path: '%kernel.project_dir%/templates'
        paths:
            '%kernel.project_dir%/vendor/acme/foo-bar/templates': foo_bar
    
        date:
            format: d.m.Y, H:i:s
            interval_format: '%%d days'
            timezone: Asia/Tokyo
        number_format:
            decimals: 2
            decimal_point: ','
            thousands_separator: '.'
    
  • XML
     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
    30
    31
    32
    33
    <!-- config/packages/twig.xml -->
    <?xml version="1.0" charset="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
            http://symfony.com/schema/dic/services/services-1.0.xsd
            http://symfony.com/schema/dic/twig http://symfony.com/schema/dic/twig/twig-1.0.xsd">
    
        <twig:config
            auto-reload="%kernel.debug%"
            autoescape="name"
            base-template-class="Twig_Template"
            cache="%kernel.cache_dir%/twig"
            charset="%kernel.charset%"
            debug="%kernel.debug%"
            strict-variables="false"
            optimizations="true"
            default-path="%kernel.project_dir%/templates"
        >
            <twig:form-theme>form_div_layout.html.twig</twig:form-theme> <!-- Default -->
            <twig:form-theme>form.html.twig</twig:form-theme>
    
            <twig:global key="foo" id="bar" type="service" />
            <twig:global key="pi">3.14</twig:global>
    
            <twig:date format="d.m.Y, H:i:s" interval-format="%d days" timezone="Asia/Tokyo" />
            <twig:number-format decimals="2" decimal-point="," thousands-separator="." />
    
            <twig:exception-controller>AcmeFooBundle:Exception:showException</twig:exception-controller>
            <twig:path namespace="foo_bar">%kernel.project_dir%/vendor/acme/foo-bar/templates</twig:path>
        </twig:config>
    </container>
    
  • PHP
     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
    30
    31
    32
    33
    34
    // config/packages/twig.php
    $container->loadFromExtension('twig', array(
        'form_themes' => array(
            'form_div_layout.html.twig', // Default
            'form.html.twig',
         ),
         'globals' => array(
             'foo' => '@bar',
             'pi'  => 3.14,
         ),
         'auto_reload'          => '%kernel.debug%',
         'autoescape'           => 'name',
         'base_template_class'  => 'Twig_Template',
         'cache'                => '%kernel.cache_dir%/twig',
         'charset'              => '%kernel.charset%',
         'debug'                => '%kernel.debug%',
         'strict_variables'     => false,
         'exception_controller' => 'AcmeFooBundle:Exception:showException',
         'optimizations'        => true,
         'paths' => array(
             '%kernel.project_dir%/vendor/acme/foo-bar/templates' => 'foo_bar',
         ),
        'date' => array(
            'format' => 'd.m.Y, H:i:s',
            'interval_format' => '%%d days',
            'timezone' => 'Asia/Tokyo',
        ),
        'number_format' => array(
            'decimals' => 2,
            'decimal_point' => ',',
            'thousands_separator' => '.',
        ),
        'default_path' => '%kernel.project_dir%/templates',
    ));
    

Configuration

auto_reload

type: boolean default: '%kernel.debug%'

If true, whenever a template is rendered, Symfony checks first if its source code has changed since it was compiled. If it has changed, the template is compiled again automatically.

autoescape

type: boolean or string default: 'name'

If set to false, automatic escaping is disabled (you can still escape each content individually in the templates).

Caution

Setting this option to false is dangerous and it will make your application vulnerable to XSS exploits because most third-party bundles assume that auto-escaping is enabled and they don't escape contents themselves.

If set to a string, the template contents are escaped using the strategy with that name. Allowed values are html, js, css, url, html_attr and name. The default value is name. This strategy escapes contents according to the template name extension (e.g. it uses html for *.html.twig templates and js for *.js.html templates).

Tip

See autoescape_service and autoescape_service_method to define your own escaping strategy.

autoescape_service

type: string default: null

As of Twig 1.17, the escaping strategy applied by default to the template is determined during compilation time based on the filename of the template. This means for example that the contents of a *.html.twig template are escaped for HTML and the contents of *.js.twig are escaped for JavaScript.

This option allows to define the Symfony service which will be used to determine the default escaping applied to the template.

autoescape_service_method

type: string default: null

If autoescape_service option is defined, then this option defines the method called to determine the default escaping applied to the template.

base_template_class

type: string default: 'Twig_Template'

Twig templates are compiled into PHP classes before using them to render contents. This option defines the base class from which all the template classes extend. Using a custom base template is discouraged because it will make your application harder to maintain.

cache

type: string default: '%kernel.cache_dir%/twig'

Before using the Twig templates to render some contents, they are compiled into regular PHP code. Compilation is a costly process, so the result is cached in the directory defined by this configuration option.

Set this option to null to disable Twig template compilation. However, this is not recommended; not even in the dev environment, because the auto_reload option ensures that cached templates which have changed get compiled again.

charset

type: string default: '%kernel.charset%'

The charset used by the template files. By default it's the same as the value of the kernel.charset container parameter, which is UTF-8 by default in Symfony applications.

date

These options define the default values used by the date filter to format date and time values. They are useful to avoid passing the same arguments on every date filter call.

format

type: string default: F j, Y H:i

The format used by the date filter to display values when no specific format is passed as argument.

internal_format

type: string default: %d days

The format used by the date filter to display DateInterval instances when no specific format is passed as argument.

timezone

type: string default: (the value returned by date_default_timezone_get())

The timezone used when formatting date values with the date filter and no specific timezone is passed as argument.

debug

type: boolean default: '%kernel.debug%'

If true, the compiled templates include a __toString() method that can be used to display their nodes.

exception_controller

type: string default: twig.controller.exception:showAction

This is the controller that is activated after an exception is thrown anywhere in your application. The default controller (ExceptionController) is what's responsible for rendering specific templates under different error conditions (see How to Customize Error Pages). Modifying this option is advanced. If you need to customize an error page you should use the previous link. If you need to perform some behavior on an exception, you should add a listener to the kernel.exception event (see kernel.event_listener).

number_format

These options define the default values used by the number_format filter to format numeric values. They are useful to avoid passing the same arguments on every number_format filter call.

decimals

type: integer default: 0

The number of decimals used to format numeric values when no specific number is passed as argument to the number_format filter.

decimal_point

type: string default: .

The character used to separate the decimals from the integer part of numeric values when no specific character is passed as argument to the number_format filter.

thousands_separator

type: string default: ,

The character used to separate every group of thousands in numeric values when no specific character is passed as argument to the number_format filter.

optimizations

type: int default: -1

Twig includes an extension called optimizer which is enabled by default in Symfony applications. This extension analyzes the templates to optimize them when being compiled. For example, if your template doesn't use the special loop variable inside a for tag, this extension removes the initialization of that unused variable.

By default, this option is -1, which means that all optimizations are turned on. Set it to 0 to disable all the optimizations. You can even enable or disable these optimizations selectively, as explained in the Twig documentation about the optimizer extension.

default_path

type: string default: '%kernel.project_dir%/templates'

The default directory where Symfony will look for Twig templates.

paths

type: array default: null

This option defines the directories where Symfony will look for Twig templates in addition to the default locations. Symfony looks for the templates in the following order:

  1. The directories defined in this option;
  2. The Resources/views/ directories of the bundles used in the application;
  3. The src/Resources/views/ directory of the application;
  4. The directory defined in the default_path option.

The values of the paths option are defined as key: value pairs where the value part can be null. For example:

  • YAML
    1
    2
    3
    4
    5
    # config/packages/twig.yaml
    twig:
        # ...
        paths:
            '%kernel.project_dir%/vendor/acme/foo-bar/templates': ~
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    <!-- 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
            http://symfony.com/schema/dic/services/services-1.0.xsd
            http://symfony.com/schema/dic/twig http://symfony.com/schema/dic/twig/twig-1.0.xsd">
    
        <twig:config>
            <!-- ... -->
            <twig:path>%kernel.project_dir%/vendor/acme/foo-bar/templates</twig:path>
        </twig:config>
    </container>
    
  • PHP
    1
    2
    3
    4
    5
    6
    7
    // config/packages/twig.php
    $container->loadFromExtension('twig', array(
        // ...
        'paths' => array(
           '%kernel.project_dir%/vendor/acme/foo-bar/templates' => null,
        ),
    ));
    

The directories defined in the paths option have more priority than the default directories defined by Symfony. In the above example, if the template exists in the acme/foo-bar/templates/ directory inside your application's vendor/, it will be used by Symfony.

If you provide a value for any path, Symfony will consider it the Twig namespace for that directory:

  • YAML
    1
    2
    3
    4
    5
    # config/packages/twig.yaml
    twig:
        # ...
        paths:
            '%kernel.project_dir%/vendor/acme/foo-bar/templates': 'foo_bar'
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    <!-- 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
            http://symfony.com/schema/dic/services/services-1.0.xsd
            http://symfony.com/schema/dic/twig http://symfony.com/schema/dic/twig/twig-1.0.xsd">
    
        <twig:config>
            <!-- ... -->
            <twig:path namespace="foo_bar">%kernel.project_dir%/vendor/acme/foo-bar/templates</twig:path>
        </twig:config>
    </container>
    
  • PHP
    1
    2
    3
    4
    5
    6
    7
    # config/packages/twig.php
    $container->loadFromExtension('twig', array(
        // ...
        'paths' => array(
           '%kernel.project_dir%/vendor/acme/foo-bar/templates' => 'foo_bar',
        ),
    ));
    

This option is useful to not mess with the default template directories defined by Symfony. Besides, it simplifies how you refer to those templates:

1
@foo_bar/template_name.html.twig

strict_variables

type: boolean default: '%kernel.debug%'

If set to true, Symfony shows an exception whenever a Twig variable, attribute or method doesn't exist. If set to false these errors are ignored and the non-existing values are replaced by null.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.