Symfony News

New in Symfony 3.4: Deprecate configuration options

Contributed by
Tobias Nyholm, Fabien Potencier, and Sanpi in #22382 and #24024.

Symfony project follows the semantic versioning strategy and a backward compatibility promise to ensure smooth upgrades of your projects. The main piece of this strategy are the deprecation messages, which warn you when using features that will be removed or changed in the next major Symfony version.

Deprecations are not only important for code changes. When using semantic configuration in your applications, it's also important to warn users about any future change in the config options. That's why in Symfony 3.4 we added a feature to simplify the deprecation of config nodes:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// ...
->scalarNode('config_option_1')
    // this outputs the following generic deprecation message:
    // The child node "config_option_1" at path "acme_root" is deprecated.
    ->setDeprecated()
->end()
->scalarNode('config_option_2')
    // you can also pass a custom deprecation message (%node% and %path% placeholders are available):
    ->setDeprecated('The "%node%" option is deprecated. Use "new_config_option" instead.')
->end()