Skip to content

[DependencyInjection] Document the different types of service arguments #21048

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: 6.4
Choose a base branch
from
Open

[DependencyInjection] Document the different types of service arguments #21048

Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
310c46c
[DependencyInjection] Document the different types of service arguments
javiereguiluz Jun 4, 2025
f1f43a7
-
javiereguiluz Jun 4, 2025
1f682ca
-
javiereguiluz Jun 4, 2025
1d11816
Fix issues
javiereguiluz Jun 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
122 changes: 122 additions & 0 deletions service_container.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -323,6 +323,128 @@

[...]

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:
# string, numeric and boolean arguments can be passed "as is"
- 'Foo'
- true
- 7
- 3.14

# 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

Check failure on line 347 in service_container.rst

View workflow job for this annotation

GitHub Actions / Code Blocks 

[Yaml syntax] The constant "App\Service\AnotherService::SOME_CONSTANT" is not defined at line 15 (near "!php/const App\Service\AnotherService::SOME_CONSTANT").
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To avoid this error, can we use a real constant from the codebase? 😄

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added it to the DOCtor-RST allow list

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This will not work, the error comes from the code-blocks checker

- !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

# binary contents are passed encoded as base64 strings
- !!binary VGhpcyBpcyBhIEJlbGwgY2hhciAH

# 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 can be strings or numbers -->
<argument>Foo</argument>
<argument>7</argument>
<argument>3.14</argument>
<!-- explicitly declare a string argument -->
<argument type="string">Foo</argument>
<!-- booleans are passed as constants -->
<argument type="constant">true</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"/>

<!-- binary contents are passed encoded as base64 strings -->
<argument type="binary">VGhpcyBpcyBhIEJlbGwgY2hhciAH</argument>

<!-- 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>

Check failure on line 408 in service_container.rst

View workflow job for this annotation

GitHub Actions / Code Blocks 

[XML syntax] Premature end of data in tag container line 2

.. 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, numeric and boolean arguments can be passed "as is"
->arg(0, 'Foo')
->arg(1, true)
->arg(2, 7)
->arg(3, 3.14)

// constants: built-in, user-defined, or Enums
->arg(4, E_ALL)
->arg(5, \PDO::FETCH_NUM)
->arg(6, \App\Service\AnotherService::SOME_CONSTANT)
->arg(7, \App\Config\SomeEnum::SomeCase)

// when not using autowiring, you can pass service arguments explicitly
->arg(8, service('some-service-id')) # fails if service doesn't exist
# passes null if service doesn't exist
->arg(9, new Reference('some-service-id', Reference::IGNORE_ON_INVALID_REFERENCE))

// collection with mixed argument types
->arg(10, [
'first' => true,
'second' => 'Foo',
]);

// ...
};

Handling Multiple Services
~~~~~~~~~~~~~~~~~~~~~~~~~~

Expand Down
Loading