[DependencyInjection] Add documentation for service locator changes

service_container/service_subscribers_locators.rst

@@ -243,8 +243,8 @@ Defining a Service Locator
 --------------------------
 
 To manually define a service locator, create a new service definition and add
-the ``container.service_locator`` tag to it. Use its ``arguments`` option to
-include as many services as needed in it.
+the ``container.service_locator`` tag to it. Use the first argument of the
+service definition to pass a collection of services to the service locator:
 
 .. configuration-block::
 
@@ -258,6 +258,9 @@ include as many services as needed in it.
                     -
                         App\FooCommand: '@app.command_handler.foo'
                         App\BarCommand: '@app.command_handler.bar'
+                        # if the element has no key, the ID of the original service is used
+                        '@app.command_handler.baz'
+
                 # if you are not using the default service autoconfiguration,
                 # add the following tag to the service definition:
                 # tags: ['container.service_locator']
@@ -274,8 +277,10 @@ include as many services as needed in it.
 
                 <service id="app.command_handler_locator" class="Symfony\Component\DependencyInjection\ServiceLocator">
                     <argument type="collection">
-                        <argument key="App\FooCommand" type="service" id="app.command_handler.foo"/>
-                        <argument key="App\BarCommand" type="service" id="app.command_handler.bar"/>
+                        <argument key="App\FooCommand" type="service" id="app.command_handler.foo" />
+                        <argument key="App\BarCommand" type="service" id="app.command_handler.bar" />
+                        <!-- if the element has no key, the ID of the original service is used -->
+                        <argument type="service" id="app.command_handler.baz" />
                     </argument>
                     <!--
                         if you are not using the default service autoconfiguration,
@@ -300,12 +305,24 @@ include as many services as needed in it.
             ->setArguments([[
                 'App\FooCommand' => new Reference('app.command_handler.foo'),
                 'App\BarCommand' => new Reference('app.command_handler.bar'),
-            ]])
+                // if the element has no key, the ID of the original service is used
+                new Reference('app.command_handler.baz'),
+            )))
             // if you are not using the default service autoconfiguration,
             // add the following tag to the service definition:
             // ->addTag('container.service_locator')
         ;
 
+.. versionadded:: 4.1
+    The service locator autoconfiguration was introduced in Symfony 4.1. In
+    previous Symfony versions you always needed to add the
+    ``container.service_locator`` tag explicitly.
+
+.. versionadded:: 4.2
+
+    The ability to add services without specifying their id was introduced in
+    Symfony 4.2.
+
 .. note::
 
     The services defined in the service locator argument must include keys,