8000 Merge branch '2.3' into 2.7 · symfony/symfony-docs@373ef72 · GitHub
[go: up one dir, main page]
Skip to content

Commit 373ef72

Browse files
weaverryanweaverryan
committed
Merge branch '2.3' into 2.7
* 2.3: [#6472] Updating description, after change Avoid confusion Added file paths Fixes and rewords Documented the config options of TwigBundle [#6427] Adding a header Tests: Explain how to add or remove data in a collection of forms Document constraint validator alias optional
2 parents 54d2df5 + 71fef2f commit 373ef72

File tree

4 files changed

+247
-13
lines changed

4 files changed

+247
-13
lines changed

‎book/testing.rst

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -711,6 +711,51 @@ their type::
711711
PHP format (it converts the keys with square brackets notation - e.g.
712712
``my_form[subject]`` - to PHP arrays).
713713

714+
Adding and Removing Forms to a Collection
715+
.........................................
716+
717+
If you use a :doc:`Collection of Forms </cookbook/form/form_collections>`,
718+
you can't add fields to an existing form with
719+
``$form['task[tags][0][name]'] = 'foo';``. This results in an error
720+
``Unreachable field "…"`` because ``$form`` can only be used in order to
721+
set values of existing fields. In order to add new fields, you have to
722+
add the values to the raw data array::
723+
724+
// Get the form.
725+
$form = $crawler->filter('button')->form();
726+
727+
// Get the raw values.
728+
$values = $form->getPhpValues();
729+
730+
// Add fields to the raw values.
731+
$values['task']['tag'][0]['name'] = 'foo';
732+
$values['task']['tag'][1]['name'] = 'bar';
733+
734+
// Submit the form with the existing and new values.
735+
$crawler = $this->client->request($form->getMethod(), $form->getUri(), $values,
736+
$form->getPhpFiles());
737+
738+
// The 2 tags have been added to the collection.
739+
$this->assertEquals(2, $crawler->filter('ul.tags > li')->count());
740+
741+
Where ``task[tags][0][name]`` is the name of a field created
742+
with JavaScript.
743+
744+
You can remove an existing field, e.g. a tag::
745+
746+
// Get the values of the form.
747+
$values = $form->getPhpValues();
748+
749+
// Remove the first tag.
750+
unset($values['task']['tags'][0]);
751+
752+
// Submit the data.
753+
$crawler = $client->request($form->getMethod(), $form->getUri(),
754+
$values, $form->getPhpFiles());
755+
756+
// The tag has been removed.
757+
$this->assertEquals(0, $crawler->filter('ul.tags > li')->count());
758+
714759
.. index::
715760
pair: Tests; Configuration
716761

‎book/translation.rst

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -440,10 +440,11 @@ need it::
440440
$request = $event->getRequest();
441441

442442
// some logic to determine the $locale
443-
$request->getSession()->set('_locale', $locale);
443+
$request->setLocale($locale);
444444
}
445445

446-
Read :doc:`/cookbook/session/locale_sticky_session` for more on the topic.
446+
Read :doc:`/cookbook/session/locale_sticky_session` for more information on making
447+
the user's locale "sticky" to their session.
447448

448449
.. note::
449450

‎cookbook/validation/custom_constraint.rst

Lines changed: 4 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -167,7 +167,7 @@ Constraint Validators with Dependencies
167167
If your constraint validator has dependencies, such as a database connection,
168168
it will need to be configured as a service in the Dependency Injection
169169
Container. This service must include the ``validator.constraint_validator``
170-
tag and an ``alias`` attribute:
170+
tag and may include an ``alias`` attribute:
171171

172172
.. configuration-block::
173173

@@ -195,21 +195,14 @@ tag and an ``alias`` attribute:
195195
->register('validator.unique.your_validator_name', 'Fully\Qualified\Validator\Class\Name')
196196
->addTag('validator.constraint_validator', array('alias' => 'alias_name'));
197197
198-
Your constraint class should now use this alias to reference the appropriate
199-
validator::
198+
As mentioned above, Symfony will automatically look for a class named after
199+
the constraint, with ``Validator`` appended. You can override this in your constraint class::
200200

201201
public function validatedBy()
202202
{
203-
return 'alias_name';
203+
return 'Fully\Qualified\ConstraintValidator\Class\Name'; // or 'alias_name' if provided
204204
}
205205

206-
As mentioned above, Symfony will automatically look for a class named after
207-
the constraint, with ``Validator`` appended. If your constraint validator
208-
is defined as a service, it's important that you override the
209-
``validatedBy()`` method to return the alias used when defining your service,
210-
otherwise Symfony won't use the constraint validator service, and will
211-
instantiate the class instead, without any dependencies injected.
212-
213206
Class Constraint Validator
214207
~~~~~~~~~~~~~~~~~~~~~~~~~~
215208

‎reference/configuration/twig.rst

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -115,6 +115,76 @@ TwigBundle Configuration ("twig")
115115
Configuration
116116
-------------
117117

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

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

0 commit comments

Comments
 (0)
0