8000 Documented the config options of TwigBundle · linaori/symfony-docs@37ef9bb · GitHub
[go: up one dir, main page]
Skip to content

Commit 37ef9bb

Browse files
javiereguiluzweaverryan
javiereguiluz
authored and
weaverryan
committed
Documented the config options of TwigBundle
1 parent c241299 commit 37ef9bb

File tree

1 file changed

+187
-0
lines changed

1 file changed

+187
-0
lines changed

‎reference/configuration/twig.rst

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,74 @@ Configuration
105105

106106
.. _config-twig-exception-controller:
107107

108+
auto_reload
109+
~~~~~~~~~~~
110+
111+
**type**: ``boolean`` **default**: ``'%kernel.debug%'``
112+
113+
If ``true``, whenever a template is rendered, Symfony checks first if its source
114+
code has changed since it was compiled. If it has changed, the template is
115+
compiled again automatically.
116+
117+
autoescape_service
118+
~~~~~~~~~~~~~~~~~~
119+
120+
**type**: ``string`` **default**: ``null``
121+
122+
As of Twig 1.17, the escaping strategy applied by default to the template is
123+
determined during compilation time based on the filename of the template. This
124+
means for example that the contents of a ``*.html.twig`` template are escaped
125+
for HTML and the contents of ``*.js.twig`` are escaped for JavaScript.
126+
127+
This option allows to define the Symfony service which will be used to determine
128+
the default escaping applied to the template.
129+
130+
autoescape_service_method
131+
~~~~~~~~~~~~~~~~~~~~~~~~~
132+
133+
**type**: ``string`` **default**: ``null``
134+
135+
If ``autoescape_service`` option is defined, then this option defines the method
136+
called to determine the default escaping applied to the template.
137+
138+
base_template_class
139+
~~~~~~~~~~~~~~~~~~~
140+
141+
**type**: ``string`` **default**: ``'Twig_Template'``
142+
143+
Twig templates are compiled into PHP classes before using them to render
144+
contents. This option defines the base class from which all the template classes
145+
extend. Using a custom base template is discouraged because it will make your
146+
application harder to maintain.
147+
148+
cache
149+
~~~~~
150+
151+
**type**: ``string`` **default**: ``'%kernel.cache_dir%/twig'``
152+
153+
Before using the Twig templates to render some contents, they are compiled into
154+
regular PHP code. Compilation is a costly process, so the result is cached in
155+
the directory defined by this configuration option.
156+
157+
Set this option to ``null`` to disable Twig template compilation. However, this
158+
is not recommended (even for the ``dev`` environment).
159+
160+
charset
161+
~~~~~~~
162+
163+
**type**: ``string`` **default**: ``'%kernel.charset%'``
164+
165+
The charset used by the template files. In Symfony Standard edition this defaults
166+
to ``UTF-8`` charset.
167+
168+
debug
169+
~~~~~
170+
171+
**type**: ``boolean`` **default**: ``'%kernel.debug%'``
172+
173+
If ``true``, the compiled templates include a ``__toString()`` method that can
174+
be used to display their nodes.
175+
108176
exception_controller
109177
~~~~~~~~~~~~~~~~~~~~
110178

@@ -118,3 +186,122 @@ conditions (see :doc:`/cookbook/controller/error_pages`). Modifying this
118186
option is advanced. If you need to customize an error page you should use
119187
the previous link. If you need to perform some behavior on an exception,
120188
you should add a listener to the ``kernel.exception`` event (see :ref:`dic-tags-kernel-event-listener`).
189+
190+
optimizations
191+
~~~~~~~~~~~~~
192+
193+
**type**: ``int`` **default**: ``-1``
194+
195+
Twig includes an extension called ``optimizer`` which is enabled by default in
196+
Symfony applications. This extension analyzes the templates to optimize them
197+
when being compiled. For example, if your template doesn't use the special
198+
``loop`` variable inside a ``for`` tag, this extension removes the initialization
199+
of that unused variable.
200+
201+
By default, this option is ``-1``, which means that all optimizations are turned
202+
on. Set it to ``0`` to disable all the optimizations. You can even enable or
203+
disable these optimizations selectively, as explained in the Twig documentation
204+
about `the optimizer extension`_.
205+
206+
paths
207+
~~~~~
208+
209+
**type**: ``array`` **default**: ``null``
210+
211+
This option defines the directories where Symfony will look for Twig templates
212+
in addition to the default locations (``app/Resources/views/`` and the bundles'
213+
``Resources/views/`` directories). This is useful to integrate the templates
214+
included in some library or package used by your application.
215+
216+
The values of the ``paths`` option are defined as ``key: value`` pairs where the
217+
``value`` part can be ``null``. For example:
218+
219+
.. configuration-block::
220+
221+
.. code-block:: yaml
222+
223+
twig:
224+
# ...
225+
paths:
226+
'%kernel.root_dir%/../vendor/acme/foo-bar/templates': ~
227+
228+
.. code-block:: xml
229+
230+
<container xmlns="http://symfony.com/schema/dic/services"
231+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
232+
xmlns:twig="http://symfony.com/schema/dic/twig"
233+
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
234+
http://symfony.com/schema/dic/twig http://symfony.com/schema/dic/twig/twig-1.0.xsd">
235+
236+
<twig:config>
237+
<!-- ... -->
238+
<twig:path>%kernel.root_dir%/../vendor/acme/foo-bar/templates</twig:path>
239+
</twig:config>
240+
</container>
241+
242+
.. code-block:: php
243+
244+
$container->loadFromExtension('twig', array(
245+
// ...
246+
'paths' => array(
247+
'%kernel.root_dir%/../vendor/acme/foo-bar/templates' => null,
248+
),
249+
));
250+
251+
The directories defined in the ``paths`` option have more priority than the
252+
default directories defined by Symfony. In the above example, if the template
253+
exists in the ``acme/foo-bar/templates/`` directory inside your application's
254+
``vendor/``, it will be used by Symfony.
255+
256+
If you provide a value for any path, Symfony will consider it the Twig namespace
257+
for that directory:
258+
259+
.. configuration-block::
260+
261+
.. code-block:: yaml
262+
263+
twig:
264+
# ...
265+
paths:
266+
'%kernel.root_dir%/../vendor/acme/foo-bar/templates': 'foo_bar'
267+
268+
.. code-block:: xml
269+
270+
<container xmlns="http://symfony.com/schema/dic/services"
271+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
272+
xmlns:twig="http://symfony.com/schema/dic/twig"
273+
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
274+
http://symfony.com/schema/dic/twig http://symfony.com/schema/dic/twig/twig-1.0.xsd">
275+
276+
<twig:config>
277+
<!-- ... -->
278+
<twig:path namspace="foo_bar">%kernel.root_dir%/../vendor/acme/foo-bar/templates</twig:path>
279+
</twig:config>
280+
</container>
281+
282+
.. code-block:: php
283+
284+
$container->loadFromExtension('twig', array(
285+
// ...
286+
'paths' => array(
287+
'%kernel.root_dir%/../vendor/acme/foo-bar/templates' => 'foo_bar',
288+
),
289+
));
290+
291+
This option is useful to not mess with the default template directories defined
292+
by Symfony. Besides, it simplifies how you refer to those templates:
293+
294+
.. code-block:: text
295+
296+
@foo_bar/template_name.html.twig
297+
298+
strict_variables
299+
~~~~~~~~~~~~~~~~
300+
301+
**type**: ``boolean`` **default**: ``'%kernel.debug%'``
302+
303+
If set to ``true``, Symfony shows an exception whenever a Twig variable,
304+
attribute or method doesn't exist. If set to ``false`` these errors are ignored
305+
and the non-existing values are replaced by ``null``.
306+
307+
.. _`the optimizer extension`: http://twig.sensiolabs.org/doc/api.html#optimizer-extension

0 commit comments

Comments
 (0)
0