How to Create Friendly Configuration for a Bundle

Using the AbstractBundle Class

In bundles extending the AbstractBundle class, you can add all the logic related to processing the configuration in that class:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

// src/AcmeSocialBundle.php
namespace Acme\SocialBundle;

use Symfony\Component\Config\Definition\Configurator\DefinitionConfigurator;
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
use Symfony\Component\HttpKernel\Bundle\AbstractBundle;

class AcmeSocialBundle extends AbstractBundle
{
    public function configure(DefinitionConfigurator $definition): void
    {
        $definition->rootNode()
            ->children()
                ->arrayNode('twitter')
                    ->children()
                        ->integerNode('client_id')->end()
                        ->scalarNode('client_secret')->end()
                    ->end()
                ->end() // twitter
            ->end()
        ;
    }

    public function loadExtension(array $config, ContainerConfigurator $container, ContainerBuilder $builder): void
    {
        // the "$config" variable is already merged and processed so you can
        // use it directly to configure the service container (when defining an
        // extension class, you also have to do this merging and processing)
        $container->services()
            ->get('acme_social.twitter_client')
            ->arg(0, $config['twitter']['client_id'])
            ->arg(1, $config['twitter']['client_secret'])
        ;
    }
}

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

// src/AcmeSocialBundle.php
namespace Acme\SocialBundle;

// ...
class AcmeSocialBundle extends AbstractBundle
{
    public function configure(DefinitionConfigurator $definition): void
    {
        $definition->import('../config/definition.php');
        // you can also use glob patterns
        //$definition->import('../config/definition/*.php');
    }

    // ...
}

1
2
3
4
5
6
7
8
9
10

// config/definition.php
use Symfony\Component\Config\Definition\Configurator\DefinitionConfigurator;

return static function (DefinitionConfigurator $definition): void {
    $definition->rootNode()
        ->children()
            ->scalarNode('foo')->defaultValue('bar')->end()
        ->end()
    ;
};

Using the Bundle Extension

This is the traditional way of creating friendly configuration for bundles. For new bundles it's recommended to use the main bundle class, but the traditional way of creating an extension class still works.

Imagine you are creating a new bundle - AcmeSocialBundle - which provides integration with X/Twitter. To make your bundle configurable to the user, you can add some configuration that looks like this:

1
2
3
4
5

# config/packages/acme_social.yaml
acme_social:
    twitter:
        client_id: 123
        client_secret: your_secret

1
2
3
4
5
6
7
8
9
10
11

// config/packages/acme_social.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'acme_social' => [
        'twitter' => [
            'client_id' => 123,
            'client_secret' => 'your_secret',
        ],
    ],
]);

The basic idea is that instead of having the user override individual parameters, you let the user configure just a few, specifically created, options. As the bundle developer, you then parse through that configuration and load correct services and parameters inside an "Extension" class.

1
2
3
4
5
6
7
8

[
    [
        'twitter' => [
            'client_id' => 123,
            'client_secret' => 'your_secret',
        ],
    ],
]

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

[
    // values from config/packages/acme_social.yaml
    [
        'twitter' => [
            'client_id' => 123,
            'client_secret' => 'your_secret',
        ],
    ],
    // values from config/packages/dev/acme_social.yaml
    [
        'twitter' => [
            'client_id' => 456,
        ],
    ],
]

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

// src/DependencyInjection/Configuration.php
namespace Acme\SocialBundle\DependencyInjection;

use Symfony\Component\Config\Definition\Builder\TreeBuilder;
use Symfony\Component\Config\Definition\ConfigurationInterface;

class Configuration implements ConfigurationInterface
{
    public function getConfigTreeBuilder(): TreeBuilder
    {
        $treeBuilder = new TreeBuilder('acme_social');

        $treeBuilder->getRootNode()
            ->children()
                ->arrayNode('twitter')
                    ->children()
                        ->integerNode('client_id')->end()
                        ->scalarNode('client_secret')->end()
                    ->end()
                ->end() // twitter
            ->end()
        ;

        return $treeBuilder;
    }
}

1
2
3
4
5
6
7
8
9
10

// src/DependencyInjection/AcmeSocialExtension.php
public function load(array $configs, ContainerBuilder $container): void
{
    $configuration = new Configuration();

    $config = $this->processConfiguration($configuration, $configs);

    // you now have these 2 config keys
    // $config['twitter']['client_id'] and $config['twitter']['client_secret']
}

1
2
3
4
5
6
7
8
9
10

// src/Resources/config/services.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use Acme\SocialBundle\TwitterClient;

return function (ContainerConfigurator $container) {
    $container->services()
        ->set('acme_social.twitter_client', TwitterClient::class)
            ->args([abstract_arg('client_id'), abstract_arg('client_secret')]);
};

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

// src/DependencyInjection/AcmeSocialExtension.php
namespace Acme\SocialBundle\DependencyInjection;

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

public function load(array $configs, ContainerBuilder $container): void
{
    $loader = new PhpFileLoader($container, new FileLocator(dirname(__DIR__).'/Resources/config'));
    $loader->load('services.php');

    $configuration = new Configuration();
    $config = $this->processConfiguration($configuration, $configs);

    $definition = $container->getDefinition('acme_social.twitter_client');
    $definition->replaceArgument(0, $config['twitter']['client_id']);
    $definition->replaceArgument(1, $config['twitter']['client_secret']);
}

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

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

use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\HttpKernel\DependencyInjection\ConfigurableExtension;

class AcmeHelloExtension extends ConfigurableExtension
{
    // note that this method is called loadInternal and not load
    protected function loadInternal(array $mergedConfig, ContainerBuilder $container): void
    {
        // ...
    }
}

1
2
3
4
5
6
7
8
9
10

public function load(array $configs, ContainerBuilder $container): void
{
    $config = [];
    // let resources override the previous set value
    foreach ($configs as $subConfig) {
        $config = array_merge($config, $subConfig);
    }

    // ... now use the flat $config array
}

Modifying the Configuration of Another Bundle

If you have multiple bundles that depend on each other, it may be useful to allow one Extension class to modify the configuration passed to another bundle's Extension class. This can be achieved using a prepend extension. For more details, see How to Simplify Configuration of Multiple Bundles.

Forwarding a Configuration Section to Another Bundle

When a section of your bundle configuration moves to another bundle, you can keep supporting the old key so existing applications don't break. Use the aliasOf() method to declare that the section belongs to the configuration of the other bundle, passing the root key of that configuration:

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

// src/AcmeSocialBundle.php
namespace Acme\SocialBundle;

use Symfony\Component\Config\Definition\Configurator\DefinitionConfigurator;
use Symfony\Component\HttpKernel\Bundle\AbstractBundle;

class AcmeSocialBundle extends AbstractBundle
{
    public function configure(DefinitionConfigurator $definition): void
    {
        $definition->rootNode()
            ->children()
                // this section is now handled by AcmeBlueskyBundle
                ->variableNode('bluesky')->aliasOf('acme_bluesky')
                    // optionally, ask users to move to the new key (the
                    // deprecation is only triggered if the old key is used)
                    ->setDeprecated('acme/social-bundle', '2.1')
                ->end()
            ->end()
        ;
    }
}

Symfony moves the contents of the old key to the configuration of the other bundle, so the following configuration is processed as if it were written under the acme_bluesky key:

1
2
3
4

# config/packages/acme_social.yaml
acme_social:
    bluesky:
        handle: acme.example.com

1
2
3
4
5
6
7
8
9
10

// config/packages/acme_social.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'acme_social' => [
        'bluesky' => [
            'handle' => 'acme.example.com',
        ],
    ],
]);

This happens after all bundles have prepended their configuration and before any of them is loaded, so the configuration that other bundles prepend under the old key is forwarded too.

If an application uses both keys, the values of the old key are merged first, so the values defined under acme_bluesky take precedence.

The alias node normalizes the value before forwarding it, so it can keep accepting a shorthand of the old section. For example, to accept a string as the value of the handle option:

1
2
3
4
5
6
7
8
9
10
11

$definition->rootNode()
    ->children()
        ->variableNode('bluesky')->aliasOf('acme_bluesky')
            // "bluesky: acme.example.com" becomes "bluesky: { handle: ... }"
            ->beforeNormalization()
                ->ifString()
                ->then(static fn (string $handle) => ['handle' => $handle])
            ->end()
        ->end()
    ->end()
;

Keep in mind the following restrictions:

• only the direct children of the root node can be aliases and they must accept arrays (use a variableNode(), because the other bundle already validates the contents of the section);
• after normalization, the value must be an array or null (which is forwarded as an empty array);
• aliases can't be chained, so the alias must point to the bundle that actually handles the section.

Dump the Configuration

The config:dump-reference command dumps the default configuration of a bundle in the console using the Yaml format.

As long as your bundle's configuration is located in the standard location (<YourBundle>/src/DependencyInjection/Configuration) and does not have a constructor, it will work automatically. If you have something different, your Extension class must override the Extension::getConfiguration() method and return an instance of your Configuration.

Exporting the Configuration for IDEs

When the container is compiled in debug mode, FrameworkBundle exports the configuration tree of every registered bundle into the config/reference.php and config/schema.json files of the application. IDEs and static analyzers use them to autocomplete and validate the application configuration (see Configuring Symfony).

These files are meant for applications only, so your bundle must not rely on their contents.

Both files are built from the configuration tree, so avoid changing the shape of the configuration in beforeNormalization() closures. The exports only include the input type checked by methods like ifString() or ifArray(), while closures added with methods like always() or ifTrue() are ignored. In both cases, the alternative shapes that your closures accept are not described, so tools can't autocomplete or validate those options. Prefer defining explicit nodes so that the accepted structure appears in both files.