Merge branch '6.1' into 6.2

* 6.1:
  Merged the new example into the existing configuration block
  [DependencyInjection] Autowire arguments using the #[TaggedLocator] attribute
  [DependencyInjection] Autowire arguments using the #[TaggedIterator] attribute

Author: javiereguiluz

service_container/service_subscribers_locators.rst

@@ -300,10 +300,45 @@ Defining a Service Locator
 --------------------------
 
 To manually define a service locator and inject it to another service, create an
-argument of type ``service_locator``:
+argument of type ``service_locator``.
+
+Consider the following ``CommandBus`` class where you want to inject
+some services into it via a service locator::
+
+    // src/HandlerCollection.php
+    namespace App;
+
+    use Symfony\Component\DependencyInjection\ServiceLocator;
+
+    class CommandBus
+    {
+        public function __construct(ServiceLocator $locator)
+        {
+        }
+    }
+
+Symfony allows you to inject the service locator using YAML/XML/PHP configuration
+or directly via PHP attributes:
 
 .. configuration-block::
 
+    .. conde-block:: php-attributes
+
+        // src/CommandBus.php
+        namespace App;
+
+        use Symfony\Component\DependencyInjection\Attribute\TaggedLocator;
+        use Symfony\Component\DependencyInjection\ServiceLocator;
+
+        class CommandBus
+        {
+            public function __construct(
+                // creates a service locator with all the services tagged with 'app.handler'
+                #[TaggedLocator('app.handler')] ServiceLocator $locator
+            ) {
+            }
+        }
+
     .. code-block:: yaml
 
         # config/services.yaml
@@ -510,7 +545,7 @@ will share identical locators among all the services referencing them::
             // ...
             'logger' => new Reference('logger'),
         ];
-        
+
         $myService = $container->findDefinition(MyService::class);
 
         $myService->addArgument(ServiceLocatorTagPass::register($container, $locateableServices));

service_container/tags.rst

@@ -511,11 +511,40 @@ Symfony provides a shortcut to inject all services tagged with a specific tag,
 which is a common need in some applications, so you don't have to write a
 compiler pass just for that.
 
-In the following example, all services tagged with ``app.handler`` are passed as
-first  constructor argument to the ``App\HandlerCollection`` service:
+Consider the following ``HandlerCollection`` class where you want to inject
+all services tagged with ``app.handler`` into its constructor argument::
+
+    // src/HandlerCollection.php
+    namespace App;
+
+    class HandlerCollection
+    {
+        public function __construct(iterable $handlers)
+        {
+        }
+    }
+
+Symfony allows you to inject the services using YAML/XML/PHP configuration or
+directly via PHP attributes:
 
 .. configuration-block::
 
+    .. code-block:: php-attributes
+
+        // src/HandlerCollection.php
+        namespace App;
+
+        use Symfony\Component\DependencyInjection\Attribute\TaggedIterator;
+
+        class HandlerCollection
+        {
+            public function __construct(
+                // the attribute must be applied directly to the argument to autowire
+                #[TaggedIterator('app.handler')] iterable $handlers
+            ) {
+            }
+        }
+
     .. code-block:: yaml
 
         # config/services.yaml
@@ -578,24 +607,26 @@ first  constructor argument to the ``App\HandlerCollection`` service:
             ;
         };
 
-After compilation the ``HandlerCollection`` service is able to iterate over your
-application handlers::
-
-    // src/HandlerCollection.php
-    namespace App;
-
-    class HandlerCollection
-    {
-        public function __construct(iterable $handlers)
-        {
-        }
-    }
-
 If for some reason you need to exclude one or more services when using a tagged
 iterator, add the ``exclude`` option:
 
 .. configuration-block::
 
+    .. code-block:: php-attributes
+
+        // src/HandlerCollection.php
+        namespace App;
+
+        use Symfony\Component\DependencyInjection\Attribute\TaggedIterator;
+
+        class HandlerCollection
+        {
+            public function __construct(
+                #[TaggedIterator('app.handler', exclude: ['App\Handler\Three'])] iterable $handlers
+            ) {
+            }
+        }
+
     .. code-block:: yaml
 
         # config/services.yaml