[DependencyInjection] Document the different types of service arguments

Author: javiereguiluz

service_container.rst

@@ -323,6 +323,104 @@ type-hints by running:
 
       [...]
 
+In addition to injecting services, you can also pass scalar values and collections
+as arguments of other services:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/services.yaml
+        services:
+            App\Service\SomeService:
+                arguments:
+                    # arguments without a type are treated as strings
+                    - 'Foo'
+                    # explicitly declare a string argument
+                    - !str 'Foo'
+                    # constants can be built-in, user-defined, or Enums
+                    - !php/const true
+                    - !php/const E_ALL
+                    - !php/const PDO::FETCH_NUM
+                    - !php/const App\Service\AnotherService::SOME_CONSTANT
+                    - !php/const App\Config\SomeEnum::SomeCase
+                    # when not using autowiring, you can pass service arguments explicitly
+                    - '@some-service-id'  # the leading '@' tells this is a service ID, not a string
+                    - '@?some-service-id' # using '?' means to pass null if service doesn't exist
+                    # collections (arrays) can include any type of argument
+                    -
+                        first: !php/const true
+                        second: 'Foo'
+
+    .. 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"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+            <services>
+                <service id="App\Service\SomeService">
+                    <!-- arguments without a type are treated as strings -->
+                    <argument>Foo</argument>
+                    <!-- explicitly declare a string argument -->
+                    <argument type="string">Foo</argument>
+                    <!-- constants can be built-in, user-defined, or Enums -->
+                    <argument type="constant">true</argument>
+                    <argument type="constant">E_ALL</argument>
+                    <argument type="constant">PDO::FETCH_NUM</argument>
+                    <argument type="constant">App\Service\AnotherService::SOME_CONSTANT</argument>
+                    <argument type="constant">App\Config\SomeEnum::SomeCase</argument>
+                    <!-- when not using autowiring, you can pass service arguments explicitly -->
+                    <argument type="service"
+                              id="some-service-id"
+                              on-invalid="dependency_injection-ignore" />
+                    <!-- collections (arrays) can include any type of argument -->
+                    <argument type="collection">
+                        <argument key="first" type="constant">true</argument>
+                        <argument key="second" type="string">Foo</argument>
+                    </argument>
+                </service>
+
+                <!-- ... -->
+            </services>
+
+    .. code-block:: php
+
+        // config/services.php
+        namespace Symfony\Component\DependencyInjection\Loader\Configurator;
+
+        use Symfony\Component\DependencyInjection\ContainerInterface;
+        use Symfony\Component\DependencyInjection\Reference;
+
+        return static function (ContainerConfigurator $container) {
+            $services = $container->services();
+
+            $services->set(App\Service\SomeService::class)
+                // string arguments
+                ->arg(0, 'Foo')
+                // constants: built-in, user-defined, or Enums
+                ->arg(1, true)
+                ->arg(2, E_ALL)
+                ->arg(3, \PDO::FETCH_NUM)
+                ->arg(4, \App\Service\AnotherService::SOME_CONSTANT)
+                ->arg(5, \App\Config\SomeEnum::SomeCase)
+                // explicit service reference with on-invalid behavior
+                ->arg(6, new Reference('some-service-id', Reference::IGNORE_ON_INVALID_REFERENCE))
+                // collection with mixed argument types
+                ->arg(7, [
+                    'first' => true,
+                    'second' => 'Foo',
+                ]);
+
+            // ...
+        };
+
 Handling Multiple Services
 ~~~~~~~~~~~~~~~~~~~~~~~~~~