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;
  バンドルの DependencyInjection 名前空間に存在する必要があります。
• It has to implement the ExtensionInterface, which is usually achieved by extending the Extension class;
  通常、Extension クラスを拡張することによって実現される ExtensionInterface を実装する必要があります。
• 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).
  この名前は、バンドルの接尾辞を Extension に置き換えたバンドル名と同じです (たとえば、AcmeBundle の Extension クラスは AcmeExtension と呼ばれ、AcmeHelloBundle の拡張クラスは 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)
    {
        // ... 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).

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)
{
    $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 $container, ContainerBuilder $builder): void
    {
        // load an XML, PHP or Yaml file
        $container->import('../config/services.xml');

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

        if ($config['scream']) {
            $container->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)
{
    // ...

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

        // ...
    ]);
}

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.