minor #18892 [DependencyInjection] Reword the explanation about index_by and default_index_method (javiereguiluz)

This PR was squashed before being merged into the 5.4 branch.

Discussion
----------

[DependencyInjection] Reword the explanation about index_by and default_index_method

Fixes #18725.

Commits
-------

87e5baa [DependencyInjection] Reword the explanation about index_by and default_index_method

Author: javiereguiluz

service_container/service_subscribers_locators.rst

@@ -507,12 +507,15 @@ will share identical locators among all the services referencing them::
 Indexing the Collection of Services
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Services passed to the service locator can define their own index using an
-arbitrary attribute whose name is defined as ``index_by`` in the service locator.
+By default, services passed to the service locator are indexed using their service
+IDs. You can change this behavior with two options of the tagged locator (``index_by``
+and ``default_index_method``) which can be used independently or combined.
 
-In the following example, the ``App\Handler\HandlerCollection`` locator receives
-all services tagged with ``app.handler`` and they are indexed using the value
-of the ``key`` tag attribute (as defined in the ``index_by`` locator option):
+The ``index_by`` / ``indexAttribute`` Option
+............................................
+
+This option defines the name of the option/attribute that stores the value used
+to index the services:
 
 .. configuration-block::
 
@@ -592,12 +595,13 @@ of the ``key`` tag attribute (as defined in the ``index_by`` locator option):
 
             $services->set(App\Handler\HandlerCollection::class)
                 // inject all services tagged with app.handler as first argument
-                ->args([tagged_locator('app.handler', 'key')])
+                ->args([tagged_locator('app.handler', indexAttribute: 'key')])
             ;
         };
 
-Inside this locator you can retrieve services by index using the value of the
-``key`` attribute. For example, to get the ``App\Handler\Two`` service::
+In this example, the ``index_by`` option is ``key``. All services define that
+option/attribute, so that will be the value used to index the services. For example,
+to get the ``App\Handler\Two`` service::
 
     // src/Handler/HandlerCollection.php
     namespace App\Handler;
@@ -608,31 +612,25 @@ Inside this locator you can retrieve services by index using the value of the
     {
         public function __construct(ServiceLocator $locator)
         {
+            // this value is defined in the `key` option of the service
             $handlerTwo = $locator->get('handler_two');
         }
 
         // ...
     }
 
-Instead of defining the index in the service definition, you can return its
-value in a method called ``getDefaultIndexName()`` inside the class associated
-to the service::
-
-    // src/Handler/One.php
-    namespace App\Handler;
+If some service doesn't define the option/attribute configured in ``index_by``,
+Symfony applies this fallback process:
 
-    class One
-    {
-        public static function getDefaultIndexName(): string
-        {
-            return 'handler_one';
-        }
+#. If the service class defines a static method called ``getDefault<CamelCase index_by value>Name``
+   (in this example, ``getDefaultKeyName()``), call it and use the returned value;
+#. Otherwise, fall back to the default behavior and use the service ID.
 
-        // ...
-    }
+The ``default_index_method`` Option
+...................................
 
-If you prefer to use another method name, add a ``default_index_method``
-attribute to the locator service defining the name of this custom method:
+This option defines the name of the service class method that will be called to
+get the value used to index the services:
 
 .. configuration-block::
 
@@ -647,7 +645,7 @@ attribute to the locator service defining the name of this custom method:
         class CommandBus
         {
             public function __construct(
-                #[TaggedLocator('app.handler', 'key', defaultIndexMethod: 'myOwnMethodName')]
+                #[TaggedLocator('app.handler', defaultIndexMethod: 'getLocatorKey')]
                 ServiceLocator $locator
             ) {
             }
@@ -659,8 +657,9 @@ attribute to the locator service defining the name of this custom method:
         services:
             # ...
 
-            App\HandlerCollection:
-                arguments: [!tagged_locator { tag: 'app.handler', index_by: 'key', default_index_method: 'myOwnMethodName' }]
+            App\Handler\HandlerCollection:
+                # inject all services tagged with app.handler as first argument
+                arguments: [!tagged_locator { tag: 'app.handler', default_index_method: 'getLocatorKey' }]
 
     .. code-block:: xml
 
@@ -672,11 +671,11 @@ attribute to the locator service defining the name of this custom method:
                 https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
-
                 <!-- ... -->
 
                 <service id="App\HandlerCollection">
-                    <argument type="tagged_locator" tag="app.handler" index-by="key" default-index-method="myOwnMethodName"/>
+                    <!-- inject all services tagged with app.handler as first argument -->
+                    <argument type="tagged_locator" tag="app.handler" default-index-method="getLocatorKey"/>
                 </service>
             </services>
         </container>
@@ -687,17 +686,27 @@ attribute to the locator service defining the name of this custom method:
         namespace Symfony\Component\DependencyInjection\Loader\Configurator;
 
         return function(ContainerConfigurator $container) {
-            $container->services()
-                ->set(App\HandlerCollection::class)
-                    ->args([tagged_locator('app.handler', 'key', 'myOwnMethodName')])
+            $services = $container->services();
+            // ...
+
+            $services->set(App\Handler\HandlerCollection::class)
+                // inject all services tagged with app.handler as first argument
+                ->args([tagged_locator('app.handler', defaultIndexMethod: 'getLocatorKey')])
             ;
         };
 
-.. note::
+If some service class doesn't define the method configured in ``default_index_method``,
+Symfony will fall back to using the service ID as its index inside the locator.
+
+Combining the ``index_by`` and ``default_index_method`` Options
+...............................................................
+
+You can combine both options in the same locator. Symfony will process them in
+the following order:
 
-    Since code should not be responsible for defining how the locators are
-    going to be used, a configuration key (``key`` in the example above) must
-    be set so the custom method may be called as a fallback.
+#. If the service defines the option/attribute configured in ``index_by``, use it;
+#. If the service class defines the method configured in ``default_index_method``, use it;
+#. Otherwise, fall back to using the service ID as its index inside the locator.
 
 .. _service-subscribers-service-subscriber-trait:
 

service_container/tags.rst

@@ -922,12 +922,15 @@ you can define it in the configuration of the collecting service:
 Tagged Services with Index
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you want to retrieve a specific service within the injected collection
-you can use the ``index_by`` and ``default_index_method`` options of the
-argument in combination with ``!tagged_iterator``.
+By default, tagged services are indexed using their service IDs. You can change
+this behavior with two options of the tagged iterator (``index_by`` and
+``default_index_method``) which can be used independently or combined.
 
-Using the previous example, this service configuration creates a collection
-indexed by the ``key`` attribute:
+The ``index_by`` / ``indexAttribute`` Option
+............................................
+
+This option defines the name of the option/attribute that stores the value used
+to index the services:
 
 .. configuration-block::
 
@@ -1012,10 +1015,9 @@ indexed by the ``key`` attribute:
             ;
         };
 
-After compilation the ``HandlerCollection`` is able to iterate over your
-application handlers. To retrieve a specific service from the iterator, call the
-``iterator_to_array()`` function and then use the ``key`` attribute to get the
-array element. For example, to retrieve the ``handler_two`` handler::
+In this example, the ``index_by`` option is ``key``. All services define that
+option/attribute, so that will be the value used to index the services. For example,
+to get the ``App\Handler\Two`` service::
 
     // src/Handler/HandlerCollection.php
     namespace App\Handler;
@@ -1026,43 +1028,23 @@ array element. For example, to retrieve the ``handler_two`` handler::
         {
             $handlers = $handlers instanceof \Traversable ? iterator_to_array($handlers) : $handlers;
 
+            // this value is defined in the `key` option of the service
             $handlerTwo = $handlers['handler_two'];
         }
     }
 
-You can omit the index attribute (``key`` in the previous example) by setting
-the ``index_by`` attribute on the ``tagged_iterator`` tag. In this case, you
-must define a static method whose name follows the pattern:
-``getDefault<CamelCase index_by value>Name``.
-
-For example, if ``index_by`` is ``handler``, the method name must be
-``getDefaultHandlerName()``:
-
-.. code-block:: yaml
+If some service doesn't define the option/attribute configured in ``index_by``,
+Symfony applies this fallback process:
 
-    # config/services.yaml
-        services:
-            # ...
+#. If the service class defines a static method called ``getDefault<CamelCase index_by value>Name``
+   (in this example, ``getDefaultKeyName()``), call it and use the returned value;
+#. Otherwise, fall back to the default behavior and use the service ID.
 
-            App\HandlerCollection:
-                arguments: [!tagged_iterator { tag: 'app.handler', index_by: 'handler' }]
+The ``default_index_method`` Option
+...................................
 
-.. code-block:: php
-
-    // src/Handler/One.php
-    namespace App\Handler;
-
-    class One
-    {
-        // ...
-        public static function getDefaultHandlerName(): string
-        {
-            return 'handler_one';
-        }
-    }
-
-You also can define the name of the static method to implement on each service
-with the ``default_index_method`` attribute on the tagged argument:
+This option defines the name of the service class method that will be called to
+get the value used to index the services:
 
 .. configuration-block::
 
@@ -1089,7 +1071,6 @@ with the ``default_index_method`` attribute on the tagged argument:
             # ...
 
             App\HandlerCollection:
-                # use getIndex() instead of getDefaultIndexName()
                 arguments: [!tagged_iterator { tag: 'app.handler', default_index_method: 'getIndex' }]
 
     .. code-block:: xml
@@ -1105,7 +1086,6 @@ with the ``default_index_method`` attribute on the tagged argument:
                 <!-- ... -->
 
                 <service id="App\HandlerCollection">
-                    <!-- use getIndex() instead of getDefaultIndexName() -->
                     <argument type="tagged_iterator"
                         tag="app.handler"
                         default-index-method="getIndex"
@@ -1127,14 +1107,26 @@ with the ``default_index_method`` attribute on the tagged argument:
 
             // ...
 
-            // use getIndex() instead of getDefaultIndexName()
             $services->set(HandlerCollection::class)
                 ->args([
                     tagged_iterator('app.handler', null, 'getIndex'),
                 ])
             ;
         };
 
+If some service class doesn't define the method configured in ``default_index_method``,
+Symfony will fall back to using the service ID as its index inside the tagged services.
+
+Combining the ``index_by`` and ``default_index_method`` Options
+...............................................................
+
+You can combine both options in the same collection of tagged services. Symfony
+will process them in the following order:
+
+#. If the service defines the option/attribute configured in ``index_by``, use it;
+#. If the service class defines the method configured in ``default_index_method``, use it;
+#. Otherwise, fall back to using the service ID as its index inside the tagged services collection.
+
 .. _tags_as-tagged-item:
 
 The ``#[AsTaggedItem]`` attribute