Service Container Configuration Reference (DependencyInjection)

The service container is configured under the services key of any of the configuration files loaded by the application (typically config/services.yaml). This reference describes all the keys available to define and configure services in YAML, XML and PHP.

Note

When using XML, you must use the http://symfony.com/schema/dic/services namespace and the related XSD schema is available at: https://symfony.com/schema/dic/services/services-1.0.xsd

7.4

The XML format to configure services was deprecated in Symfony 7.4.

A services section is made of four kinds of entries:

`_defaults`_: values applied by default to every service defined in the same file;
`_instanceof`_: values applied to every service defined in the same file whose class matches a given type (class or interface);
Service definitions: each entry defines or overrides a service identified by its key (the service ID);
Prototypes: entries with a resource key that register as services all the classes found in a directory.

The configuration file may also contain other top-level keys that are siblings of services: imports, parameters and environment-specific configuration.

This article only documents the configuration keys themselves. For detailed explanations and examples, follow the links to the related articles.

`_defaults`

The _defaults key stores the values that are applied by default to every service defined in the same file. Each service can override any of these values:

        1
2
3
4
5
6
        # config/services.yaml
services:
    _defaults:
        autowire: true
        autoconfigure: true
        public: false
    

        1
2
3
4
5
6
7
8
9
10
11
        <!-- 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"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <defaults autowire="true" autoconfigure="true" public="false"/>
    </services>
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
        // config/services.php
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return function (ContainerConfigurator $container): void {
    $services = $container->services()
        ->defaults()
            ->autowire(true)
            ->autoconfigure(true)
            ->public(false)
    ;
};
    

The keys allowed inside _defaults are: autoconfigure, autowire, bind, public, resource_tags and tags.

autoconfigure

type: boolean default: false

When set to true, Symfony applies to every service the configuration registered for its class (for example, the tags added to all the classes that implement a given interface or that use a given PHP attribute). Read more in Service Container and Service Tags.

autowire

type: boolean default: false

When set to true, Symfony guesses the constructor and method arguments of the services based on their type-hints. Read more in Defining Service Dependencies Automatically (Autowiring).

bind

type: array default: []

Defines the values that Symfony injects in the arguments of the services. Keys can be argument names ($variableName), types (Some\Class\Name) or both (Some\Class\Name $variableName). These bindings are merged with the per-service bind option. Read more in Defining Service Dependencies Automatically (Autowiring).

public

type: boolean default: false

If true, services defined in the file can be retrieved directly from the container with $container->get(). If false (the recommended value), they can only be injected as dependencies. Read more in Service Container.

resource_tags

type: array default: []

A list of resource tags to apply to every class defined in the file. It uses the same syntax as the tags option.

7.4

The resource_tags option was introduced in Symfony 7.4.

`_instanceof`

The _instanceof key applies some configuration to every service defined in the same file whose class extends or implements a given type:

        1
2
3
4
5
6
        # config/services.yaml
services:
    _instanceof:
        App\Domain\LoaderInterface:
            public: true
            tags: ['app.loader']
    

        1
2
3
4
5
6
        <!-- config/services.xml -->
<services>
    <instanceof id="App\Domain\LoaderInterface" public="true">
        <tag name="app.loader"/>
    </instanceof>
</services>
    

        1
2
3
4
5
        // config/services.php
$services->instanceof(\App\Domain\LoaderInterface::class)
    ->public()
    ->tag('app.loader')
;
    

The keys allowed inside _instanceof are a subset of the per-service keys: autowire, bind, calls, configurator, constructor, lazy, properties, public, resource_tags, shared and tags.

Service Definitions

Each entry under services whose key is not _defaults or _instanceof defines (or overrides) a service. Its key is the service ID, which is the identifier used to reference the service from other definitions or to retrieve it from the container.

In YAML, the entry value can also be ~ (the service only uses the default configuration) or a string starting with @ (the service is an alias of that other service).

abstract

type: boolean default: false

When true, the service can't be retrieved from the container; it only serves as a template for child services (see parent). Read more in Advanced Service Definition Options.

alias

type: string default: null

When set, the service is an alias of another service, whose ID is given as the value. When defining an alias, the only other keys allowed are public and deprecated. Read more in Defining Service Dependencies Automatically (Autowiring).

arguments

type: array default: []

The arguments passed to the constructor (or to the method defined by factory). Arguments can be scalars, parameters (%kernel.cache_dir%), service references (@service.id) or any of the special argument types described in Types of Dependency Injection.

autoconfigure

type: boolean default: false

Overrides the autoconfigure value set in _defaults for this service.

autowire

type: boolean default: false

Overrides the autowire value set in _defaults for this service.

bind

type: array default: []

Argument bindings of this service, using the same syntax as the _defaults bind option. They are merged with the bindings defined in _defaults; when both define the same key, the value of the service wins. Read more in Defining Service Dependencies Automatically (Autowiring).

calls

type: array default: []

A list of methods called on the service after creating it (this is called setter injection). Each item defines the method to call, its arguments and, optionally, whether the method returns a new instance of the service instead of modifying it (!returns_clone in YAML):

        1
2
3
4
5
6
        # config/services.yaml
services:
    App\Service\MessageGenerator:
        calls:
            - setLogger: ['@logger']
            - withDispatcher: !returns_clone ['@event_dispatcher']
    

        1
2
3
4
5
6
7
8
9
        <!-- config/services.xml -->
<service id="App\Service\MessageGenerator">
    <call method="setLogger">
        <argument type="service" id="logger"/>
    </call>
    <call method="withDispatcher" returns-clone="true">
        <argument type="service" id="event_dispatcher"/>
    </call>
</service>
    

        1
2
3
4
5
6
        // config/services.php
$services->set(\App\Service\MessageGenerator::class)
    ->call('setLogger', [service('logger')])
    // the third argument tells whether the method returns a clone
    ->call('withDispatcher', [service('event_dispatcher')], true)
;
    

Read more in Types of Dependency Injection.

class

type: string default: null

The fully-qualified class name of the service. When omitted, Symfony uses the service ID as the class name, so you only need this option when the service ID is not a class name.

7.4

Omitting class when the service ID looks like a class name but no such class or interface exists was deprecated in Symfony 7.4.

configurator

type: string | array default: null

A callable executed after the service is created and its arguments, properties and method calls are set. It receives the service as its argument and applies some last-minute configuration to it:

        1
2
3
4
        # config/services.yaml
services:
    App\Service\NewsletterManager:
        configurator: ['@App\Service\NewsletterConfigurator', 'configure']
    

        1
2
3
4
5
        <!-- config/services.xml -->
<service id="App\Service\NewsletterManager">
    <configurator service="App\Service\NewsletterConfigurator"
        method="configure"/>
</service>
    

        1
2
3
4
5
6
7
        // config/services.php
$services->set(\App\Service\NewsletterManager::class)
    ->configurator([
        service(\App\Service\NewsletterConfigurator::class),
        'configure',
    ])
;
    

constructor

type: string default: null

The name of a static method of the service class used to create the service instead of the __construct() method. It can't be combined with factory.

decorates

type: string default: null

The ID of the service decorated by this service. The decorating service replaces the decorated one in the container, and the original service remains available under another ID (see decoration_inner_name). Read more in Service Decoration.

decoration_inner_name

type: string default: <decorating_service_id>.inner

The ID under which the decorated service remains available. It's only used together with decorates.

decoration_on_invalid

type: string default: exception

Defines what happens when the decorated service doesn't exist. It's only used together with decorates. Allowed values are:

exception: an exception is thrown;
ignore: the decoration is ignored and the decorating service is removed;
null (without quotes in YAML): the decorating service is kept and null is injected instead of the decorated service.

decoration_priority

type: integer default: 0

When several services decorate the same service, this option defines the order in which they are applied. Decorators with a higher priority are applied first, so they end up closer to the decorated service. It's only used together with decorates.

deprecated

type: array default: []

Marks the service (or the alias) as deprecated, which triggers a deprecation when it's used. The package and version keys are required. The optional message key must contain the %service_id% placeholder; when omitted, Symfony uses a generic deprecation message:

        1
2
3
4
5
6
7
        # config/services.yaml
services:
    App\Service\OldService:
        deprecated:
            package: 'acme/legacy-bundle'
            version: '1.2'
            message: 'Use NewService instead of "%service_id%".'
    

        1
2
3
4
5
        <!-- config/services.xml -->
<service id="App\Service\OldService">
    <deprecated package="acme/legacy-bundle"
        version="1.2">Use NewService instead of "%service_id%".</deprecated>
</service>
    

        1
2
3
4
5
6
7
8
        // config/services.php
$services->set(\App\Service\OldService::class)
    ->deprecate(
        'acme/legacy-bundle',
        '1.2',
        'Use NewService instead of "%service_id%".'
    )
;
    

factory

type: string | array default: null

A callable used to create the service instead of calling its constructor. It can be a static method (Acme\Factory::build), a method of another service (['@factory_service', 'build']), a PHP function (my_factory_function) or an expression (@=...). When the value is a service reference (@factory_service), the __invoke() method of that service is called. It can't be combined with constructor. Read more in Using a Factory to Create Services.

file

type: string default: null

A PHP file that Symfony requires before creating the service. It's useful for classes that can't be autoloaded.

from_callable

type: string | array default: null

Creates the service by calling Closure::fromCallable() with the given callable, so the service is a Closure. When class is set to an interface with a single method, Symfony creates instead an object that implements that interface and calls the given callable. It can't be combined with factory. Read more in Defining Service Dependencies Automatically (Autowiring).

lazy

type: boolean | string default: false

When true, Symfony injects a proxy that delays the creation of the service until it's actually used. When set to a string, that string is the interface implemented by the proxy. Read more in Lazy Services.

parent

type: string default: null

The ID of the service from which this service inherits its configuration. This service only needs to define the keys that are different from the parent service. Read more in Advanced Service Definition Options.

properties

type: array default: []

The public properties to set on the service after creating it. The keys are the property names and the values use the same syntax as arguments.

public

type: boolean default: false

Overrides the public value set in _defaults for this service. Services with the synthetic option enabled are public unless you set this option explicitly.

resource_tags

type: array default: []

A list of resource tags to apply to this class. They use the same syntax as tags, but the class is excluded from the container, so it's not registered as a service. Compiler passes can still find the class through its tags.

7.4

The resource_tags option was introduced in Symfony 7.4.

shared

type: boolean default: true

When true, the container always returns the same instance of the service. When false, it creates a new instance every time the service is requested. Read more in Advanced Service Definition Options.

stack

type: array default: null

Defines a stack of decorators registered under a single ID. Each item of the stack decorates the next one, and the service ID refers to the first item. When using stack, the only other keys allowed are public and deprecated:

        1
2
3
4
5
6
7
        # config/services.yaml
services:
    app.cache_chain:
        stack:
            - class: App\Cache\TraceableCache
              arguments: ['@.inner']
            - class: App\Cache\RedisCache
    

        1
2
3
4
5
6
7
8
9
        <!-- config/services.xml -->
<services>
    <stack id="app.cache_chain">
        <service class="App\Cache\TraceableCache">
            <argument type="service" id=".inner"/>
        </service>
        <service class="App\Cache\RedisCache"/>
    </stack>
</services>
    

        1
2
3
4
5
6
        // config/services.php
$services->stack('app.cache_chain', [
    inline_service(\App\Cache\TraceableCache::class)
        ->args([service('.inner')]),
    inline_service(\App\Cache\RedisCache::class),
]);
    

synthetic

type: boolean default: false

When true, the container doesn't create the service; your code must set it at runtime with $container->set(). Read more in Advanced Service Definition Options.

Prototypes (Loading Services from a Directory)

A prototype is an entry that registers as services all the classes found in a directory. It's identified by the resource key:

        1
2
3
4
5
6
7
8
        # config/services.yaml
services:
    App\:
        resource: '../src/'
        exclude:
            - '../src/DependencyInjection/'
            - '../src/Entity/'
            - '../src/Kernel.php'
    

        1
2
3
4
5
6
        <!-- config/services.xml -->
<services>
    <prototype namespace="App\"
        resource="../src/"
        exclude="../src/{DependencyInjection,Entity,Kernel.php}"/>
</services>
    

        1
2
3
4
5
6
7
8
        // config/services.php
$services->load('App\\', '../src/')
    ->exclude([
        '../src/DependencyInjection/',
        '../src/Entity/',
        '../src/Kernel.php',
    ])
;
    

Besides the keys listed below, prototypes accept the following keys of the service definitions, which are applied to all the services they register: abstract, arguments, autoconfigure, autowire, bind, calls, configurator, constructor, deprecated, factory, lazy, parent, properties, public, resource_tags, shared and tags.

        1
2
3
4
5
        # config/services.yaml
when@dev:
    services:
        App\Debug\Profiler:
            public: true
    

        1
2
3
4
5
6
        <!-- config/services.xml -->
<when env="dev">
    <services>
        <service id="App\Debug\Profiler" public="true"/>
    </services>
</when>
    

        1
2
3
4
        // config/services.php
if ('dev' === $container->env()) {
    $services->set(\App\Debug\Profiler::class)->public();
}
    

Importing Other Configuration Files

The top-level imports key loads other configuration files. Each item accepts the following keys:

resource (string, required): the path of the file or directory to import. Glob patterns are supported;
type (string, default: null): the loader to use (yaml, xml, php, glob, directory, etc.). When omitted, it's guessed from the resource (e.g. from the file extension);
ignore_errors (boolean | string, default: false): when true, all the errors that occur while loading the resource are ignored. When set to not_found, only the errors about missing files are ignored.

        1
2
3
4
        # config/services.yaml
imports:
    - { resource: 'legacy_services.yaml' }
    - { resource: 'services_local.yaml', ignore_errors: not_found }
    

        1
2
3
4
5
        <!-- config/services.xml -->
<imports>
    <import resource="legacy_services.yaml"/>
    <import resource="services_local.yaml" ignore-errors="not_found"/>
</imports>
    

        1
2
3
4
        // config/services.php
$container->import('legacy_services.yaml');
// the third argument configures the "ignore_errors" option
$container->import('services_local.yaml', null, 'not_found');
    