New in Symfony 5.3: Config Builder Classes

Symfony 5.3 will be released in May 2021. This is the first article of the series that shows the most important new features introduced by this Symfony version.

Contributed by
Tobias Nyholm
in #40600.

Symfony applications can use YAML, XML and/or PHP as their configuration format. Each of them has its advantages and its drawbacks, so we intend to keep supporting the three of them equally in the future.

In 2020 Symfony moved all its internal container configuration from XML to PHP thanks to a colossal community effort. This container configuration uses a fluent interface pattern based on methods like service(), args(), etc. However, the PHP configuration of packages/bundles is still based on big arrays like the following:

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

// config/packages/security.php
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $container) {
  $array = [
        'firewalls' => [
            'main' => [
                'pattern' => '^/*',
                'lazy' => true,
                'anonymous' => [],
            ],
        ],
        'access_control' => [
            ['path' => '^/admin', 'roles' => 'ROLE_ADMIN'],
        ],
    ];

    $container->extension('security', $array);
}

In Symfony 5.3 we're improving the PHP config of packages/bundles thanks to the new Config Builder Classes. These classes are generated automatically in your project build directory and transform your bundle configuration classes into fluent interface classes with methods named after your config options.

For example, in Symfony 5.3 you can keep configuring the security package with the PHP array shown above or you can use the following configuration:

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

// config/packages/security.php
use Symfony\Config\SecurityConfig;

return static function (SecurityConfig $security) {
    $security->firewall('main')
        ->pattern('^/*')
        ->lazy(true)
        ->anonymous();

    $security
        ->accessControl(['path' => '^/admin', 'roles' => 'ROLE_ADMIN']);
};

This new format is not only more concise and readable, but it's also fully autocompletable by your IDE. Best of all, the SecurityConfig class used in this example is generated automatically by Symfony. We didn't have to change anything in the security package.

These config builders are created for all packages/bundles of the application (even your own). For example, if you create a bundle with the acme_foo extension alias, Symfony will generate the Symfony\Config\AcmeFooConfig class for you (if your dependency injection extension changes, the class is regenerated; there's a cache warmer to generate all config classes; etc.).

We intend to keep supporting YAML, XML and PHP formats equally in the future, but we hope that these new config builders will make you give PHP config a try. The new PHP config is as concise and readable as YAML, it provides better autocompletion than XML and it requires zero dependencies and extensions.