Merge branch '5.1' into master

* 5.1:
  Removed versionadded 4.4 directives
  [#12697] Some minor tweaks
  [DependencyInjection] Add docs for default priority method for tagged services
  [#12461] Added versionadded directive
  List CSV encoder's context options

Author: wouterj

components/serializer.rst

@@ -1295,6 +1295,48 @@ These are the options available:
 ``remove_empty_tags``
     If set to true, removes all empty tags in the generated XML (default: ``false``).
 
+The ``CsvEncoder``
+------------------
+
+This encoder transforms arrays into CSV and vice versa.
+
+Context
+~~~~~~~
+
+The ``encode()`` method defines a third optional parameter called ``context``
+which defines the configuration options for the CsvEncoder an associative array::
+
+    $csvEncoder->encode($array, 'csv', $context);
+
+These are the options available:
+
+``csv_delimiter``
+    Sets the field delimiter separating values (one character only, default: ``,``).
+
+``csv_enclosure``
+    Sets the field enclosure (one character only, default: ``"``).
+
+``csv_escape_char``
+    Sets the escape character (at most one character, default: empty string).
+
+``csv_key_separator``
+    Sets the separator for array's keys during its flattening (default: ``.``).
+
+``csv_headers``
+    Sets the headers for the data (default: ``[]``, inferred from input data's keys).
+
+``csv_escape_formulas``
+    Escapes fields containg formulas by prepending them with a ``\t`` character (default: ``false``).
+
+``as_collection``
+    Always returns results as a collection, even if only one line is decoded.
+
+``no_headers``
+    Disables header in the encoded CSV (default: ``false``).
+
+``output_utf8_bom``
+    Outputs special `UTF-8 BOM`_ along with encoded data (default: ``false``).
+
 Handling Constructor Arguments
 ------------------------------
 
@@ -1549,6 +1591,7 @@ Learn more
 .. _YAML: https://yaml.org/
 .. _CSV: https://tools.ietf.org/html/rfc4180
 .. _`RFC 7807`: https://tools.ietf.org/html/rfc7807
+.. _`UTF-8 BOM`: https://en.wikipedia.org/wiki/Byte_order_mark
 .. _`Value Objects`: https://en.wikipedia.org/wiki/Value_object
 .. _`API Platform`: https://api-platform.com
 .. _`list of PHP timezones`: https://www.php.net/manual/en/timezones.php

service_container/tags.rst

@@ -587,47 +587,113 @@ application handlers::
         }
     }
 
-.. tip::
+Tagged Services with Priority
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    The collected services can be prioritized using the ``priority`` attribute:
+The tagged services can be prioritized using the ``priority`` attribute,
+thus providing a way to inject a sorted collection of services:
 
-    .. configuration-block::
+.. configuration-block::
 
-        .. code-block:: yaml
+    .. code-block:: yaml
 
-            # config/services.yaml
-            services:
-                App\Handler\One:
-                    tags:
-                        - { name: 'app.handler', priority: 20 }
+        # config/services.yaml
+        services:
+            App\Handler\One:
+                tags:
+                    - { name: 'app.handler', priority: 20 }
 
-        .. code-block:: xml
+    .. code-block:: xml
 
-            <!-- config/services.xml -->
-            <?xml version="1.0" encoding="UTF-8" ?>
-            <container xmlns="http://symfony.com/schema/dic/services"
-                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-                xsi:schemaLocation="http://symfony.com/schema/dic/services
-                    https://symfony.com/schema/dic/services/services-1.0.xsd">
+        <!-- config/services.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
-                <services>
-                    <service id="App\Handler\One">
-                        <tag name="app.handler" priority="20"/>
-                    </service>
-                </services>
-            </container>
+            <services>
+                <service id="App\Handler\One">
+                    <tag name="app.handler" priority="20"/>
+                </service>
+            </services>
+        </container>
 
-        .. code-block:: php
+    .. code-block:: php
 
-            // config/services.php
-            namespace Symfony\Component\DependencyInjection\Loader\Configurator;
+        // config/services.php
+        namespace Symfony\Component\DependencyInjection\Loader\Configurator;
 
-            return function(ContainerConfigurator $configurator) {
-                $services = $configurator->services();
+        use App\Handler\One;
 
-                $services->set(App\Handler\One::class)
-                    ->tag('app.handler', ['priority' => 20])
-                ;
-            };
+        return function(ContainerConfigurator $configurator) {
+            $services = $configurator->services();
+
+            $services->set(One::class)
+                ->tag('app.handler', ['priority' => 20])
+            ;
+        };
 
-    Note that any other custom attributes will be ignored by this feature.
+Another option, which is particularly useful when using autoconfiguring
+tags, is to implement the static ``getDefaultPriority()`` method on the
+service itself::
+
+    // src/Handler/One.php
+    namespace App/Handler;
+
+    class One
+    {
+        public static function getDefaultPriority(): int
+        {
+            return 3;
+        }
+    }
+
+If you want to have another method defining the priority, you can define it
+in the configuration of the collecting service:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/services.yaml
+        services:
+            App\HandlerCollection:
+                # inject all services tagged with app.handler as first argument
+                arguments:
+                    - !tagged_iterator { tag: app.handler, default_priority_method: getPriority }
+
+    .. code-block:: xml
+
+        <!-- config/services.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
+            <services>
+                <service id="App\HandlerCollection">
+                    <argument type="tagged" tag="app.handler" default-priority-method="getPriority"/>
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // config/services.php
+        namespace Symfony\Component\DependencyInjection\Loader\Configurator;
+
+        use Symfony\Component\DependencyInjection\Argument\TaggedIteratorArgument;
+
+        return function (ContainerConfigurator $configurator) {
+            $services = $configurator->services();
+
+            // ...
+
+            $services->set(App\HandlerCollection::class)
+                ->args([
+                        tagged_iterator('app.handler', null, null, 'getPriority'),
+                    ]
+                )
+                ;
+        };