.. index::
pair: Twig; Configuration reference
.. configuration-block::
.. code-block:: yaml
# app/config/config.yml
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
# Foundation
- foundation_5_layout.html.twig
# Example:
- MyBundle::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: ~
paths:
'%kernel.project_dir%/vendor/acme/foo-bar/templates': foo_bar
.. code-block:: xml
<!-- app/config/config.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"
>
<twig:form-theme>form_div_layout.html.twig</twig:form-theme> <!-- Default -->
<twig:form-theme>MyBundle::form.html.twig</twig:form-theme>
<twig:global key="foo" id="bar" type="service" />
<twig:global key="pi">3.14</twig:global>
<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>
.. code-block:: php
// app/config/config.php
$container->loadFromExtension('twig', array(
'form_themes' => array(
'form_div_layout.html.twig', // Default
'MyBundle::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',
),
));
Caution!
The twig.form (<twig:form /> tag for xml) configuration key
has been deprecated and will be removed in 3.0. Instead, use the twig.form_themes
option.
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.
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.
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.
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.
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.
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.
type: string default: '%kernel.charset%'
The charset used by the template files. In the Symfony Standard edition this
defaults to the UTF-8 charset.
type: boolean default: '%kernel.debug%'
If true, the compiled templates include a __toString() method that can
be used to display their nodes.
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
(:class:`Symfony\\Bundle\\TwigBundle\\Controller\\ExceptionController`)
is what's responsible for rendering specific templates under different error
conditions (see :doc:`/controller/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 :ref:`dic-tags-kernel-event-listener`).
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.
type: array default: null
This option defines the directories where Symfony will look for Twig templates
in addition to the default locations (app/Resources/views/ and the bundles'
Resources/views/ directories). This is useful to integrate the templates
included in some library or package used by your application.
The values of the paths option are defined as key: value pairs where the
value part can be null. For example:
.. configuration-block::
.. code-block:: yaml
# app/config/config.yml
twig:
# ...
paths:
'%kernel.project_dir%/vendor/acme/foo-bar/templates': ~
.. code-block:: xml
<!-- app/config/config.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>
.. code-block:: php
// app/config/config.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:
.. configuration-block::
.. code-block:: yaml
# app/config/config.yml
twig:
# ...
paths:
'%kernel.project_dir%/vendor/acme/foo-bar/templates': 'foo_bar'
.. code-block:: xml
<!-- app/config/config.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>
.. code-block:: php
# app/config/config.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:
@foo_bar/template_name.html.twig
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.