Merge branch '5.4' into 6.2

* 5.4:
  Don't use double backquotes in the comments
  [Form] Add some basic docs for Twig Form field helpers

Author: javiereguiluz

components/cache/adapters/array_cache_adapter.rst

@@ -15,7 +15,7 @@ method::
         // until the current PHP process finishes)
         $defaultLifetime = 0,
 
-        // if ``true``, the values saved in the cache are serialized before storing them
+        // if true, the values saved in the cache are serialized before storing them
         $storeSerialized = true,
 
         // the maximum lifetime (in seconds) of the entire cache (after this time, the

event_dispatcher.rst

@@ -779,7 +779,7 @@ could listen to the ``mailer.post_send`` event and change the method's return va
         public function onMailerPostSend(AfterSendMailEvent $event)
         {
             $returnValue = $event->getReturnValue();
-            // modify the original ``$returnValue`` value
+            // modify the original $returnValue value
 
             $event->setReturnValue($returnValue);
         }

form/form_customization.rst

@@ -87,6 +87,50 @@ control over how each form field is rendered, so you can fully customize them:
     Later in this article you can find the full reference of these Twig
     functions with more usage examples.
 
+.. _reference-forms-twig-field-helpers:
+
+Form Field Helpers
+------------------
+
+The ``form_*()`` helpers shown in the previous section render different parts of
+the form field, including all its HTML elements. Some developers and designers
+struggle with this behavior, because it hides all the HTML elements in form
+themes which are not trivial to customize.
+
+That's why Symfony provides other Twig form helpers that render the value of
+each form field part without adding any HTML around it:
+
+* ``field_name()``
+* ``field_value()``
+* ``field_label()``
+* ``field_help()``
+* ``field_errors()``
+* ``field_choices()`` (an iterator for choice fields; e.g. for ``<select>``)
+
+When using these helpers, you must write all the HTML contents for all form
+fields, so you no longer have to deal with form themes:
+
+.. code-block:: html+twig
+
+    <input
+        name="{{ field_name(form.username) }}"
+        value="{{ field_value(form.username) }}"
+        placeholder="{{ field_label(form.username) }}"
+        class="form-control"
+    />
+
+    <select name="{{ field_name(form.country) }}" class="form-control">
+        <option value="">{{ field_label(form.country) }}</option>
+
+        {% for label, value in field_choices(form.country) %}
+            <option value="{{ value }}">{{ label }}</option>
+        {% endfor %}
+    </select>
+
+.. versionadded:: 5.2
+
+    The ``field_*()`` helpers were introduced in Symfony 5.2.
+
 Form Rendering Variables
 ------------------------
 

reference/twig_reference.rst

@@ -349,6 +349,12 @@ explained in the article about :doc:`customizing form rendering </form/form_cust
 * :ref:`form_help() <reference-forms-twig-help>`
 * :ref:`form_row() <reference-forms-twig-row>`
 * :ref:`form_rest() <reference-forms-twig-rest>`
+* :ref:`field_name() <reference-forms-twig-field-helpers>`
+* :ref:`field_value() <reference-forms-twig-field-helpers>`
+* :ref:`field_label() <reference-forms-twig-field-helpers>`
+* :ref:`field_help() <reference-forms-twig-field-helpers>`
+* :ref:`field_errors() <reference-forms-twig-field-helpers>`
+* :ref:`field_choices() <reference-forms-twig-field-helpers>`
 
 .. _reference-twig-filters:
 

service_container/autowiring.rst

@@ -212,8 +212,8 @@ adding a service alias:
                 # ...
 
             # but this fixes it!
-            # the ``app.rot13.transformer`` service will be injected when
-            # an ``App\Util\Rot13Transformer`` type-hint is detected
+            # the "app.rot13.transformer" service will be injected when
+            # an App\Util\Rot13Transformer type-hint is detected
             App\Util\Rot13Transformer: '@app.rot13.transformer'
 
     .. code-block:: xml
@@ -247,8 +247,8 @@ adding a service alias:
                 ->autowire();
 
             // but this fixes it!
-            // the ``app.rot13.transformer`` service will be injected when
-            // an ``App\Util\Rot13Transformer`` type-hint is detected
+            // the "app.rot13.transformer" service will be injected when
+            // an App\Util\Rot13Transformer type-hint is detected
             $services->alias(Rot13Transformer::class, 'app.rot13.transformer');
         };
 
@@ -352,8 +352,8 @@ To fix that, add an :ref:`alias <service-autowiring-alias>`:
 
             $services->set(Rot13Transformer::class);
 
-            // the ``App\Util\Rot13Transformer`` service will be injected when
-            // an ``App\Util\TransformerInterface`` type-hint is detected
+            // the App\Util\Rot13Transformer service will be injected when
+            // an App\Util\TransformerInterface type-hint is detected
             $services->alias(TransformerInterface::class, Rot13Transformer::class);
         };
 
@@ -518,13 +518,13 @@ the injection::
             $services->set(Rot13Transformer::class)->autowire();
             $services->set(UppercaseTransformer::class)->autowire();
 
-            // the ``App\Util\UppercaseTransformer`` service will be
-            // injected when an ``App\Util\TransformerInterface``
-            // type-hint for a ``$shoutyTransformer`` argument is detected.
+            // the App\Util\UppercaseTransformer service will be
+            // injected when an App\Util\TransformerInterface
+            // type-hint for a $shoutyTransformer argument is detected.
             $services->alias(TransformerInterface::class.' $shoutyTransformer', UppercaseTransformer::class);
 
             // If the argument used for injection does not match, but the
-            // type-hint still matches, the ``App\Util\Rot13Transformer``
+            // type-hint still matches, the App\Util\Rot13Transformer
             // service will be injected.
             $services->alias(TransformerInterface::class, Rot13Transformer::class);
 

testing.rst

@@ -566,11 +566,10 @@ In the above example, the test validates that the HTTP response was successful
 and the request body contains a ``<h1>`` tag with ``"Hello world"``.
 
 The ``request()`` method also returns a crawler, which you can use to
-create more complex assertions in your tests::
+create more complex assertions in your tests (e.g. to count the number of page
+elements that match a given CSS selector)::
 
     $crawler = $client->request('GET', '/post/hello-world');
-
-    // for instance, count the number of ``.comment`` elements on the page
     $this->assertCount(4, $crawler->filter('.comment'));
 
 You can learn more about the crawler in :doc:`/testing/dom_crawler`.