An Example: Client Scope

Other than the request service (which has a simple solution, see the above note), no services in the default Symfony2 container belong to any scope other than container and prototype. But for the purposes of this entry, imagine there is another scope client and a service client_configuration that belongs to it. This is not a common situation, but the idea is that you may enter and exit multiple client scopes during a request, and each has its own client_configuration service.

Scopes add a constraint on the dependencies of a service: a service cannot depend on services from a narrower scope. For example, if you create a generic my_foo service, but try to inject the client_configuration service, you will receive a ScopeWideningInjectionException when compiling the container. Read the sidebar below for more details.

A) Using a Synchronized Service

Both injecting the container and setting your service to a narrower scope have drawbacks. Assume first that the client_configuration service has been marked as synchronized:

1
2
3
4
5
6
7
8

# app/config/config.yml
services:
    client_configuration:
        class:        AppBundle\Client\ClientConfiguration
        scope:        client
        synchronized: true
        synthetic:    true
        # ...

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

<!-- app/config/config.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
        http://symfony.com/schema/dic/services/services-1.0.xsd"
    >

    <services>
        <service
            id="client_configuration"
            scope="client"
            synchronized="true"
            synthetic="true"
            class="AppBundle\Client\ClientConfiguration"
        />
    </services>
</container>

1
2
3
4
5
6
7
8
9
10
11

// app/config/config.php
use Symfony\Component\DependencyInjection\Definition;

$definition = new Definition(
    'AppBundle\Client\ClientConfiguration',
    array()
);
$definition->setScope('client');
$definition->setSynchronized(true);
$definition->setSynthetic(true);
$container->setDefinition('client_configuration', $definition);

Now, if you inject this service using setter injection, there are no drawbacks and everything works without any special code in your service or in your definition:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// src/AppBundle/Mail/Mailer.php
namespace AppBundle\Mail;

use AppBundle\Client\ClientConfiguration;

class Mailer
{
    protected $clientConfiguration;

    public function setClientConfiguration(ClientConfiguration $clientConfiguration = null)
    {
        $this->clientConfiguration = $clientConfiguration;
    }

    public function sendEmail()
    {
        if (null === $this->clientConfiguration) {
            // throw an error?
        }

        // ... do something using the client configuration here
    }
}

Whenever the client scope is active, the service container will automatically call the setClientConfiguration() method when the client_configuration service is set in the container.

You might have noticed that the setClientConfiguration() method accepts null as a valid value for the client_configuration argument. That's because when leaving the client scope, the client_configuration instance can be null. Of course, you should take care of this possibility in your code. This should also be taken into account when declaring your service:

1
2
3
4
5
6

# app/config/services.yml
services:
    my_mailer:
        class: AppBundle\Mail\Mailer
        calls:
            - [setClientConfiguration, ["@?client_configuration="]]

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<!-- app/config/services.xml -->
<services>
    <service id="my_mailer"
        class="AppBundle\Mail\Mailer"
    >
        <call method="setClientConfiguration">
            <argument
                type="service"
                id="client_configuration"
                on-invalid="null"
                strict="false"
            />
        </call>
    </service>
</services>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// app/config/services.php
use Symfony\Component\DependencyInjection\Definition;
use Symfony\Component\DependencyInjection\ContainerInterface;

$definition = $container->setDefinition(
    'my_mailer',
    new Definition('AppBundle\Mail\Mailer')
)
->addMethodCall('setClientConfiguration', array(
    new Reference(
        'client_configuration',
        ContainerInterface::NULL_ON_INVALID_REFERENCE,
        false
    )
));

B) Changing the Scope of your Service

Changing the scope of a service should be done in its definition. This example assumes that the Mailer class has a __construct function whose first argument is the ClientConfiguration object:

1
2
3
4
5
6

# app/config/services.yml
services:
    my_mailer:
        class: AppBundle\Mail\Mailer
        scope: client
        arguments: ["@client_configuration"]

1
2
3
4
5
6
7
8

<!-- app/config/services.xml -->
<services>
    <service id="my_mailer"
            class="AppBundle\Mail\Mailer"
            scope="client">
            <argument type="service" id="client_configuration" />
    </service>
</services>

1
2
3
4
5
6
7
8
9
10

// app/config/services.php
use Symfony\Component\DependencyInjection\Definition;

$definition = $container->setDefinition(
    'my_mailer',
    new Definition(
        'AppBundle\Mail\Mailer',
        array(new Reference('client_configuration'),
    ))
)->setScope('client');

C) Passing the Container as a Dependency of your Service

Setting the scope to a narrower one is not always possible (for instance, a twig extension must be in the container scope as the Twig environment needs it as a dependency). In these cases, you can pass the entire container into your service:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// src/AppBundle/Mail/Mailer.php
namespace AppBundle\Mail;

use Symfony\Component\DependencyInjection\ContainerInterface;

class Mailer
{
    protected $container;

    public function __construct(ContainerInterface $container)
    {
        $this->container = $container;
    }

    public function sendEmail()
    {
        $request = $this->container->get('client_configuration');
        // ... do something using the client configuration here
    }
}

The service config for this class would look something like this:

1
2
3
4
5
6

# app/config/services.yml
services:
    my_mailer:
        class:     AppBundle\Mail\Mailer
        arguments: ["@service_container"]
        # scope: container can be omitted as it is the default

1
2
3
4
5
6

<!-- app/config/services.xml -->
<services>
    <service id="my_mailer" class="AppBundle\Mail\Mailer">
         <argument type="service" id="service_container" />
    </service>
</services>

1
2
3
4
5
6
7
8

// app/config/services.php
use Symfony\Component\DependencyInjection\Definition;
use Symfony\Component\DependencyInjection\Reference;

$container->setDefinition('my_mailer', new Definition(
    'AppBundle\Mail\Mailer',
    array(new Reference('service_container'))
));