Merge branch '5.1' into 5.x

* 5.1:
  addressed issue #11786
  Add array example on ChoiceType choice_attr option
  [#13619] Moved text into a note and added versionadded
  Add wither behavior with PHP8 static return type
  [#14340] Some minor textual changes
  [Collection forms] Make javascript generic
  Updating the Installer Related Instructions
  Non-standard adder/remover methods

Author: wouterj

components/property_access.rst

@@ -408,6 +408,45 @@ and ``removeChild()`` methods to access to the ``children`` property.
 
 If available, *adder* and *remover* methods have priority over a *setter* method.
 
+Using non-standard adder/remover methods
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes, adder and remover methods don't use the standard ``add`` or ``remove`` prefix, like in this example::
+
+    // ...
+    class PeopleList
+    {
+        // ...
+
+        public function joinPeople(string $people): void
+        {
+            $this->peoples[] = $people;
+        }
+
+        public function leavePeople(string $people): void
+        {
+            foreach ($this->peoples as $id => $item) {
+                if ($people === $item) {
+                    unset($this->peoples[$id]);
+                    break;
+                }
+            }
+        }
+    }
+
+    use Symfony\Component\PropertyInfo\Extractor\ReflectionExtractor;
+    use Symfony\Component\PropertyAccess\PropertyAccessor;
+
+    $list = new PeopleList();
+    $reflectionExtractor = new ReflectionExtractor(null, null, ['join', 'leave']);
+    $propertyAccessor = new PropertyAccessor(false, false, null, true, $reflectionExtractor, $reflectionExtractor);
+    $propertyAccessor->setValue($person, 'peoples', ['kevin', 'wouter']);
+
+    var_dump($person->getPeoples()); // ['kevin', 'wouter']
+
+Instead of calling ``add<SingularOfThePropertyName>()`` and ``remove<SingularOfThePropertyName>()``, the PropertyAccess
+component will call ``join<SingularOfThePropertyName>()`` and ``leave<SingularOfThePropertyName>()`` methods.
+
 Checking Property Paths
 -----------------------
 

components/serializer.rst

@@ -896,8 +896,20 @@ The ``XmlEncoder`` will encode this object like that::
         <bar>1</bar>
     </response>
 
-Be aware that this encoder will consider keys beginning with ``@`` as attributes, and will use
-the key  ``#comment`` for encoding XML comments::
+The special ``#`` key can be used to define the data of a node::
+
+    ['foo' => ['@bar' => 'value', '#' => 'baz']];
+
+    // is encoded as follows:
+    // <?xml version="1.0"?>
+    // <response>
+    //     <foo bar="value">
+    //        baz
+    //     </foo>
+    // </response>
+
+Furthermore, keys beginning with ``@`` will be considered attributes, and
+the key  ``#comment`` can be used for encoding XML comments::
 
     $encoder = new XmlEncoder();
     $encoder->encode([
@@ -923,6 +935,34 @@ always as a collection.
     changed with the optional ``$encoderIgnoredNodeTypes`` argument of the
     ``XmlEncoder`` class constructor.
 
+The ``XmlEncoder`` Context Options
+..................................
+
+The ``encode()`` method defines a third optional parameter called ``context``
+which defines the configuration options for the XmlEncoder an associative array::
+
+    $xmlEncoder->encode($array, 'xml', $context);
+
+These are the options available:
+
+``xml_format_output``
+    If set to true, formats the generated XML with line breaks and indentation.
+
+``xml_version``
+    Sets the XML version attribute (default: ``1.1``).
+
+``xml_encoding``
+    Sets the XML encoding attribute (default: ``utf-8``).
+
+``xml_standalone``
+    Adds standalone attribute in the generated XML (default: ``true``).
+
+``xml_root_node_name``
+    Sets the root node name (default: ``response``).
+
+``remove_empty_tags``
+    If set to true, removes all empty tags in the generated XML (default: ``false``).
+
 The ``YamlEncoder``
 ~~~~~~~~~~~~~~~~~~~
 
@@ -1234,72 +1274,6 @@ you indicate that you're expecting an array instead of a single object::
     $data = ...; // The serialized data from the previous example
     $persons = $serializer->deserialize($data, 'Acme\Person[]', 'json');
 
-The ``XmlEncoder``
-------------------
-
-This encoder transforms arrays into XML and vice versa. For example, take an
-object normalized as following::
-
-    ['foo' => [1, 2], 'bar' => true];
-
-The ``XmlEncoder`` encodes this object as follows:
-
-.. code-block:: xml
-
-    <?xml version="1.0"?>
-    <response>
-        <foo>1</foo>
-        <foo>2</foo>
-        <bar>1</bar>
-    </response>
-
-The array keys beginning with ``@`` are considered XML attributes::
-
-    ['foo' => ['@bar' => 'value']];
-
-    // is encoded as follows:
-    // <?xml version="1.0"?>
-    // <response>
-    //     <foo bar="value"/>
-    // </response>
-
-Use the special ``#`` key to define the data of a node::
-
-    ['foo' => ['@bar' => 'value', '#' => 'baz']];
-
-    // is encoded as follows:
-    // <?xml version="1.0"?>
-    // <response>
-    //     <foo bar="value">baz</foo>
-    // </response>
-
-Context
-~~~~~~~
-
-The ``encode()`` method defines a third optional parameter called ``context``
-which defines the configuration options for the XmlEncoder an associative array::
-
-    $xmlEncoder->encode($array, 'xml', $context);
-
-These are the options available:
-
-``xml_format_output``
-    If set to true, formats the generated XML with line breaks and indentation.
-
-``xml_version``
-    Sets the XML version attribute (default: ``1.1``).
-
-``xml_encoding``
-    Sets the XML encoding attribute (default: ``utf-8``).
-
-``xml_standalone``
-    Adds standalone attribute in the generated XML (default: ``true``).
-
-``xml_root_node_name``
-    Sets the root node name (default: ``response``).
-
-``remove_empty_tags``
-    If set to true, removes all empty tags in the generated XML (default: ``false``).
 
 The ``CsvEncoder``
 ------------------

form/form_collections.rst

@@ -242,7 +242,13 @@ the following ``data-prototype`` attribute to the existing ``<ul>`` in your temp
 
 .. code-block:: html+twig
 
-    <ul class="tags" data-prototype="{{ form_widget(form.tags.vars.prototype)|e('html_attr') }}">
+    <ul class="tags" data-prototype="{{ form_widget(form.tags.vars.prototype)|e('html_attr') }}"></ul>
+
+Now add a button just next to the ``<ul>`` to dynamically add a new tag
+
+.. code-block:: html+twig
+
+    <button type="button" class="add_item_link" data-collection-holder-class="tags">Add a tag</button>
 
 On the rendered page, the result will look something like this:
 
@@ -274,38 +280,27 @@ On the rendered page, the result will look something like this:
     and you need to adjust the following JavaScript accordingly.
 
 The goal of this section will be to use JavaScript to read this attribute
-and dynamically add new tag forms when the user clicks a "Add a tag" link.
+and dynamically add new tag forms when the user clicks the "Add a tag" button.
 This example uses jQuery and assumes you have it included somewhere on your page.
 
-Add a ``script`` tag somewhere on your page so you can start writing some JavaScript.
-
-First, add a link to the bottom of the "tags" list via JavaScript. Second,
-bind to the "click" event of that link so you can add a new tag form (``addTagForm()``
-will be show next):
+Add a ``script`` tag somewhere on your page so you can start writing some
+JavaScript. In this script, bind to the "click" event of the "Add a tag"
+button so you can add a new tag form (``addFormToCollection()`` will be show next):
 
 .. code-block:: javascript
 
-    var $collectionHolder;
-
-    // setup an "add a tag" link
-    var $addTagButton = $('<button type="button" class="add_tag_link">Add a tag</button>');
-    var $newLinkLi = $('<li></li>').append($addTagButton);
-
     jQuery(document).ready(function() {
         // Get the ul that holds the collection of tags
-        $collectionHolder = $('ul.tags');
-
-        // add the "add a tag" anchor and li to the tags ul
-        $collectionHolder.append($newLinkLi);
-
+        var $tagsCollectionHolder = $('ul.tags');
         // count the current form inputs we have (e.g. 2), use that as the new
         // index when inserting a new item (e.g. 2)
-        $collectionHolder.data('index', $collectionHolder.find('input').length);
+        $tagsCollectionHolder.data('index', $tagsCollectionHolder.find('input').length);
 
-        $addTagButton.on('click', function(e) {
+        $('body').on('click', '.add_item_link', function(e) {
+            var $collectionHolderClass = $(e.currentTarget).data('collectionHolderClass');
             // add a new tag form (see next code block)
-            addTagForm($collectionHolder, $newLinkLi);
-        });
+            addFormToCollection($collectionHolderClass);
+        })
     });
 
 The ``addTagForm()`` function's job will be to use the ``data-prototype`` attribute
@@ -319,7 +314,10 @@ one example:
 
 .. code-block:: javascript
 
-    function addTagForm($collectionHolder, $newLinkLi) {
+    function addFormToCollection($collectionHolderClass) {
+        // Get the ul that holds the collection of tags
+        var $collectionHolder = $('.' + $collectionHolderClass);
+
         // Get the data-prototype explained earlier
         var prototype = $collectionHolder.data('prototype');
 
@@ -341,7 +339,8 @@ one example:
 
         // Display the form in the page in an li, before the "Add a tag" link li
         var $newFormLi = $('<li></li>').append(newForm);
-        $newLinkLi.before($newFormLi);
+        // Add the new form at the end of the list
+        $collectionHolder.append($newFormLi)
     }
 
 .. note::

reference/forms/types/options/choice_attr.rst.inc

@@ -13,6 +13,20 @@ If an array, the keys of the ``choices`` array must be used as keys::
     use Symfony\Component\Form\Extension\Core\Type\ChoiceType;
     // ...
 
+    $builder->add('fruits', ChoiceType::class, [
+        'choices' => [
+            'Apple' => 1,
+            'Banana' => 2,
+            'Durian' => 3,
+        ],
+        'choice_attr' => [
+            'Apple' => ['data-color' => 'Red'],
+            'Banana' => ['data-color' => 'Yellow'],
+            'Durian' => ['data-color' => 'Green'],
+        ],
+    ]);
+
+    // or use a callable
     $builder->add('attending', ChoiceType::class, [
         'choices' => [
             'Yes' => true,

service_container/calls.rst

@@ -90,9 +90,6 @@ instead of mutating the object they were called on::
     {
         private $logger;
 
-        /**
-         * @return static
-         */
         public function withLogger(LoggerInterface $logger)
         {
             $new = clone $this;
@@ -146,3 +143,31 @@ The configuration to tell the container it should do so would be like:
 
         $container->register(MessageGenerator::class)
             ->addMethodCall('withLogger', [new Reference('logger')], true);
+
+.. tip::
+
+    If autowire is enabled, you can also use annotations; with the previous
+    example it would be::
+
+        /**
+         * @required
+         * @return static
+         */
+        public function withLogger(LoggerInterface $logger)
+        {
+            $new = clone $this;
+            $new->logger = $logger;
+
+            return $new;
+        }
+
+    You can also leverage the PHP 8 ``static`` return type instead of the
+    ``@return static`` annotation. If you don't want a method with a
+    PHP 8 ``static`` return type and a ``@required`` annotation to behave as
+    a wither, you can add a ``@return $this`` annotation to disable the
+    *returns clone* feature.
+
+    .. versionadded:: 5.1
+
+        Support for the PHP 8 ``static`` return type was introduced in
+        Symfony 5.1.