8000 feature #6470 Documented the config options of TwigBundle (javieregui… · symfony/symfony-docs@34c48f1 · GitHub
[go: up one dir, main page]
Skip to content

Commit 34c48f1

Browse files
weaverryanweaverryan
committed
feature #6470 Documented the config options of TwigBundle (javiereguiluz)
This PR was submitted for the master branch but it was merged into the 2.3 branch instead (closes #6470). Discussion ---------- Documented the config options of TwigBundle | Q | A | ------------- | --- | Doc fix? | no | New docs? | yes | Applies to | 2.3+ | Fixed tickets | - Commits ------- 0d5803b Added file paths 3b1b16d Fixes and rewords 37ef9bb Documented the config options of TwigBundle
2 parents c241299 + 0d5803b commit 34c48f1

File tree

1 file changed

+195
-0
lines changed

1 file changed

+195
-0
lines changed

‎reference/configuration/twig.rst

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,76 @@ TwigBundle Configuration ("twig")
103103
Configuration
104104
-------------
105105

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

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

0 commit comments

Comments
 (0)
0