New in Symfony 5.3: Configure Multiple Environments in a Single File

Symfony 5.3 is backed by JoliCode. JoliCode is a team of passionate developers and open-source lovers, with a strong expertise in PHP & Symfony technologies. They can help you build your projects using state-of-the-art practices.

Contributed by
Nicolas Grekas
in #40214 and #40782.

Symfony defines different configuration environments so you can change your application behavior depending on where it’s run (e.g. locally in your development machine, in the production server, etc.)

The options applied to bundles/packages in all environments are defined in config/packages/ and the specific options of each environment are defined in config/packages/<environment>/.

This works well, but it’s cumbersome when the differences among environments are minimal, because you need to create/maintain another config file just to change a few config options.

That’s why in Symfony 5.3 you can also define options for different environments in a single file. The exact syntax to use depends on the format of the config file.

In YAML config files, use the when@... special key:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# config/packages/webpack_encore.yaml
webpack_encore:
    # ...
    output_path: '%kernel.project_dir%/public/build'
    strict_mode: true
    cache: false

[email protected]:
    webpack_encore:
        cache: true

[email protected]:
    webpack_encore:
        strict_mode: false

In XML config, wrap the config in the new <when> tag:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
<!-- config/packages/webpack_encore.xml -->
    <?xml version="1.0" encoding="UTF-8" ?>
    <container xmlns="...">
        <webpack-encore:config>
            <!-- ... -->
        </webpack-encore:config>

        <when env="prod">
            <webpack-encore:config>
                <!-- ... -->
            </webpack-encore:config>
        </when>

        <when env="test">
            <webpack-encore:config>
                <!-- ... -->
            </webpack-encore:config>
        </when>
    </container>

In PHP config files, use the new env() method to check in which environment is the application running:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
// config/packages/framework.php
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework, ContainerConfigurator $container) {
    // ...

    if ('prod' === $container->env()) {
        // ...
    }

    if ('test' === $container->env()) {
        $framework->test(true);
        $framework->session()->storageFactoryId('session.storage.mock_file');
    }
};

This syntax also works to define routes and services only in some environments. You can even combine all in a single file to configure some package and create services but only for some environments:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
framework:
    secret: '%env(APP_SECRET)%'

[email protected]:
    services:
        App\SomeServiceForDev: ~

[email protected]:
    framework:
        test: true
        # ...

The traditional way of using a config file per environment will keep working in the future, but we encourage you to give this new feature a try to reduce the number of config files to maintain.

Lastly, classes can now use PHP attributes to tell that they should only be registered as services in some environments:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
use Symfony\Component\DependencyInjection\Attribute\When;

#[When(env: 'dev')]
class SomeClass
{
    // ...
}

// you can apply more than one attribute to the same class:

#[When(env: 'dev')]
#[When(env: 'test')]
class AnotherClass
{
    // ...
}
Help the Symfony project!

As with any Open-Source project, contributing code or documentation is the most common way to help, but we also have a wide range of sponsoring opportunities.

New in Symfony 5.3: Configure Multiple Environments in a Single File symfony.com/blog/new-in-symfony-5-3-configure-multiple-environments-in-a-single-file

Tweet this

Comments

Great work! 🎉
Cool, but what about performance? Processing a single large file with all the data will not reduce performance compared to processing a larger number of files but a smaller size?
Is this an optional feature, and we won't be forced to use such in new projects, right?
Great work, love it thanks
@Marcin, you won't be forced to use this, but if you use Symfony Flex (which is enabled by default) some files generated automatically in your project might be using it.
It's worth to be noted, that when you use PHP configs you have to consider bundles availability through environments.

WebProfilerBundle available only for 'dev' and 'test' environments as usually, so WebProfilerConfig class will not be created for 'prod' and cannot be used in config/packages directory.
Nice! Great work! Thank you!
Thats awesome!
It makes really sense if you have tiny differences between the different stages. If you have the hundred differences between the stages, you may make something wrong. Good Job, Symfony!
Nice work. I will try to use it :)
Great contributions! Just one question: The #[When(env: 'dev')] example shows that a service is only registered for the defined environment. Is this a typo? Because the changelog says: "Add `#[When(env: 'foo')]` to skip autoregistering a class when the env doesn't match". So I understood that the class will still be registered as a service, but not autoconfigured, right?
Back to Symfony1, eh? :D
It has such possibility out of the box ;)
Login with SymfonyConnect to post a comment