From 294ac51bf0d6bea5360cb9cec4b98ff21053515a Mon Sep 17 00:00:00 2001
From: Alexandru Nastase <alexandru.nastase@outlook.com>
Date: Tue, 26 Nov 2019 08:23:12 +0100
Subject: [PATCH] [DependencyInjection] Add docs for default priority method
 for tagged services

---
 service_container/tags.rst | 136 ++++++++++++++++++++++++++++---------
 1 file changed, 104 insertions(+), 32 deletions(-)

diff --git a/service_container/tags.rst b/service_container/tags.rst
index ff56d90c73f..524096545c2 100644
--- a/service_container/tags.rst
+++ b/service_container/tags.rst
@@ -585,47 +585,119 @@ application handlers::
         }
     }
 
-.. tip::
 
-    The collected services can be prioritized using the ``priority`` attribute:
+Tagged Services with Priority
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    .. configuration-block::
+.. versionadded:: 4.4
 
-        .. code-block:: yaml
+    The ability to prioritize tagged services was introduced in Symfony 4.4.
 
-            # config/services.yaml
-            services:
-                App\Handler\One:
-                    tags:
-                        - { name: 'app.handler', priority: 20 }
+The tagged services can be prioritized using the ``priority`` attribute, thus providing 
+a way to inject a sorted collection.
 
-        .. code-block:: xml
+.. configuration-block::
 
-            <!-- 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">
+    .. code-block:: yaml
 
-                <services>
-                    <service id="App\Handler\One">
-                        <tag name="app.handler" priority="20"/>
-                    </service>
-                </services>
-            </container>
+        # config/services.yaml
+        services:
+            App\Handler\One:
+                tags:
+                    - { name: 'app.handler', priority: 20 }
 
-        .. code-block:: php
+    .. code-block:: xml
 
-            // config/services.php
-            namespace Symfony\Component\DependencyInjection\Loader\Configurator;
+        <!-- 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">
 
-            return function(ContainerConfigurator $configurator) {
-                $services = $configurator->services();
+            <services>
+                <service id="App\Handler\One">
+                    <tag name="app.handler" priority="20"/>
+                </service>
+            </services>
+        </container>
 
-                $services->set(App\Handler\One::class)
-                    ->tag('app.handler', ['priority' => 20])
-                ;
-            };
+    .. code-block:: php
+
+        // config/services.php
+        namespace Symfony\Component\DependencyInjection\Loader\Configurator;
+
+        return function(ContainerConfigurator $configurator) {
+            $services = $configurator->services();
+
+            $services->set(App\Handler\One::class)
+                ->tag('app.handler', ['priority' => 20])
+            ;
+        };
+
+.. note::
+
+    Note that any other custom attribute 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::
 
-    Note that any other custom attributes will be ignored by this feature.
+    // src/App/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'),
+                    ]
+                )
+                ;
+        };

<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'>
<html xmlns='http://www.w3.org/1999/xhtml'>
<head>
<title>pFad - Phonifier reborn</title>
<meta http-equiv='Content-Type' content='text/html; charset=utf-8' />
</head>
<body>
<h1>Pfad - The Proxy pFad of &#169; 2024 Garber Painting. All rights reserved.</h1>


<!-- Disclaimer -->
<p>Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.</p>
<br>
<p>Alternative Proxies:</p><p><a href="http://rainy.clevelandohioweatherforecast.com/php-proxy/index.php?q=https://patch-diff.githubusercontent.com/raw/symfony/symfony-docs/pull/12697.patch" target="_blank">Alternative Proxy</a></p><p><a href="http://rainy.clevelandohioweatherforecast.com/pFad/index.php?u=https://patch-diff.githubusercontent.com/raw/symfony/symfony-docs/pull/12697.patch" target="_blank">pFad Proxy</a></p><p><a href="http://rainy.clevelandohioweatherforecast.com/pFad/v3index.php?u=https://patch-diff.githubusercontent.com/raw/symfony/symfony-docs/pull/12697.patch" target="_blank">pFad v3 Proxy</a></p><p><a href="http://rainy.clevelandohioweatherforecast.com/pFad/v4index.php?u=https://patch-diff.githubusercontent.com/raw/symfony/symfony-docs/pull/12697.patch" target="_blank">pFad v4 Proxy</a></p></body>
</html>