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. By default, the Extension class must follow these conventions (but later you'll learn how to skip them if needed):

• It has to live in the DependencyInjection namespace of the bundle;
• It has to implement the ExtensionInterface, which is usually achieved by extending the Extension class;
• The name is equal to the bundle name with the Bundle suffix replaced by Extension (e.g. the Extension class of the AcmeBundle would be called AcmeExtension and the one for AcmeHelloBundle would be called AcmeHelloExtension).

This is how the extension of an AcmeHelloBundle should look like:

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

// src/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): void
    {
        // ... you'll load the files here later
    }
}

1
2
3
4
5
6
7
8
9
10
11

// ...
use Acme\HelloBundle\DependencyInjection\UnconventionalExtensionClass;
use Symfony\Component\DependencyInjection\Extension\ExtensionInterface;

class AcmeHelloBundle extends Bundle
{
    public function getContainerExtension(): ?ExtensionInterface
    {
        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).

For instance, assume you have a file called services.xml in the 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\Config\FileLocator;
use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;

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

The other available loaders are YamlFileLoader and PhpFileLoader.

Loading Services directly in your Bundle class

Alternatively, you can define and load services configuration directly in a bundle class instead of creating a specific Extension class. You can do this by extending from AbstractBundle and defining the loadExtension() method:

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

// ...
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
use Symfony\Component\HttpKernel\Bundle\AbstractBundle;

class AcmeHelloBundle extends AbstractBundle
{
    public function loadExtension(array $config, ContainerConfigurator $containerConfigurator, ContainerBuilder $containerBuilder): void
    {
        // load an XML, PHP or Yaml file
        $containerConfigurator->import('../config/services.xml');

        // you can also add or replace parameters and services
        $containerConfigurator->parameters()
            ->set('acme_hello.phrase', $config['phrase'])
        ;

        if ($config['scream']) {
            $containerConfigurator->services()
                ->get('acme_hello.printer')
                    ->class(ScreamingPrinter::class)
            ;
        }
    }
}

This method works similar to the Extension::load() method, but it uses a new API to define and import service configuration.

Adding Classes to Compile

Bundles can hint Symfony about which of their classes contain annotations so they are compiled when generating the application cache to improve the overall performance. Define the list of annotated classes to compile in the addAnnotatedClassesToCompile() method:

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

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

    $this->addAnnotatedClassesToCompile([
        // you can define the fully qualified class names...
        'Acme\\BlogBundle\\Controller\\AuthorController',
        // ... but glob patterns are also supported:
        'Acme\\BlogBundle\\Form\\**',

        // ...
    ]);
}

Patterns are transformed into the actual class namespaces using the classmap generated by Composer. Therefore, before using these patterns, you must generate the full classmap executing the dump-autoload command of Composer.