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

Symfony 5.3 is backed by:
Warning: This post is about an unsupported Symfony version. Some of this information may be out of date. Read the most recent Symfony Docs.
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
when@prod:
webpack_encore:
cache: true
when@test:
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)%'
when@dev:
services:
App\SomeServiceForDev: ~
when@test:
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.
Comments
Comments are closed.
To ensure that comments stay relevant, they are closed for old posts.
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.
It has such possibility out of the box ;)