How to Load Service Configuration inside a Bundle

Creating an Extension Class

In order to load service configuration, you have to create a Dependency Injection (DI) Extension for your bundle. This class has some conventions in order to be detected automatically. But you'll later see how you can change it to your own preferences. By default, the Extension has to comply with the following conventions:

• It has to live in the DependencyInjection namespace of the bundle;
• The name is equal to the bundle name with the Bundle suffix replaced by Extension (e.g. the Extension class of the AppBundle would be called AppExtension and the one for AcmeHelloBundle would be called AcmeHelloExtension).

The Extension class should implement the ExtensionInterface, but usually you would simply extend the Extension class:

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

// src/Acme/HelloBundle/DependencyInjection/AcmeHelloExtension.php
namespace Acme\HelloBundle\DependencyInjection;

use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\DependencyInjection\Extension\Extension;

class AcmeHelloExtension extends Extension
{
    public function load(array $configs, ContainerBuilder $container)
    {
        // ... you'll load the files here later
    }
}

1
2
3
4
5
6
7
8
9
10

// ...
use Acme\HelloBundle\DependencyInjection\UnconventionalExtensionClass;

class AcmeHelloBundle extends Bundle
{
    public function getContainerExtension()
    {
        return new UnconventionalExtensionClass();
    }
}

Using the load() Method

In the load() method, all services and parameters related to this extension will be loaded. This method doesn't get the actual container instance, but a copy. This container only has the parameters from the actual container. After loading the services and parameters, the copy will be merged into the actual container, to ensure all services and parameters are also added to the actual container.

In the load() method, you can use PHP code to register service definitions, but it is more common if you put these definitions in a configuration file (using the Yaml, XML or PHP format). Luckily, you can use the file loaders in the extension!

For instance, assume you have a file called services.xml in the Resources/config directory of your bundle, your load() method looks like:

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

use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;
use Symfony\Component\Config\FileLocator;

// ...
public function load(array $configs, ContainerBuilder $container)
{
    $loader = new XmlFileLoader(
        $container,
        new FileLocator(__DIR__.'/../Resources/config')
    );
    $loader->load('services.xml');
}

Other available loaders are the YamlFileLoader, PhpFileLoader and IniFileLoader.

Adding Classes to Compile

Symfony creates a big classes.php file in the cache directory to aggregate the contents of the PHP classes that are used in every request. This reduces the I/O operations and increases the application performance.

Your bundles can also add their own classes into this file thanks to the addClassesToCompile() method. Define the classes to compile as an array of their fully qualified class names:

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

use AppBundle\Manager\UserManager;
use AppBundle\Utils\Slugger;

// ...
public function load(array $configs, ContainerBuilder $container)
{
    // ...

    $this->addClassesToCompile(array(
        UserManager::class,
        Slugger::class,
        // ...
    ));
}

Beware that this technique can't be used in some cases:

• When classes contain annotations, such as controllers with @Route annotations and entities with @ORM or @Assert annotations, because the file location retrieved from PHP reflection changes;
• When classes use the __DIR__ and __FILE__ constants, because their values will change when loading these classes from the classes.php file.