From 82a44b2b7275b4924b6c482d223e6f56354e7c0e Mon Sep 17 00:00:00 2001 From: Wouter de Jong Date: Sat, 11 Apr 2020 18:30:19 +0200 Subject: [PATCH] [OptionsResolver][Config][DI] Added package and version to deprecation features --- components/config/definition.rst | 17 ++++++++++-- components/options_resolver.rst | 25 +++++++++++++---- service_container/alias_private.rst | 43 ++++++++++++++++++++--------- 3 files changed, 63 insertions(+), 22 deletions(-) diff --git a/components/config/definition.rst b/components/config/definition.rst index ae7f09a6530..ec51e8b6bd0 100644 --- a/components/config/definition.rst +++ b/components/config/definition.rst @@ -435,6 +435,13 @@ The following example shows these methods in practice:: Deprecating the Option ---------------------- +.. versionadded:: 5.1 + + The signature of the ``setDeprecated()`` method changed from + ``setDeprecated(?string $message)`` to + ``setDeprecated(string $package, string $version, ?string $message)`` + in Symfony 5.1. + You can deprecate options using the :method:`Symfony\\Component\\Config\\Definition\\Builder\\NodeDefinition::setDeprecated` method:: @@ -443,11 +450,15 @@ method:: ->children() ->integerNode('old_option') // this outputs the following generic deprecation message: - // The child node "old_option" at path "..." is deprecated. - ->setDeprecated() + // Since acme/package 1.2: The child node "old_option" at path "..." is deprecated. + ->setDeprecated('acme/package', '1.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.') + ->setDeprecated( + 'acme/package', + '1.2', + 'The "%node%" option is deprecated. Use "new_config_option" instead.' + ) ->end() ->end() ; diff --git a/components/options_resolver.rst b/components/options_resolver.rst index 9c7d31d5813..45126fe9e3b 100644 --- a/components/options_resolver.rst +++ b/components/options_resolver.rst @@ -720,18 +720,31 @@ In same way, parent options can access to the nested options as normal arrays:: Deprecating the Option ~~~~~~~~~~~~~~~~~~~~~~ +.. versionadded:: 5.1 + + The signature of the ``setDeprecated()`` method changed from + ``setDeprecated(string $option, ?string $message)`` to + ``setDeprecated(string $option, string $package, string $version, ?string $message)`` + in Symfony 5.1. + Once an option is outdated or you decided not to maintain it anymore, you can deprecate it using the :method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::setDeprecated` method:: $resolver ->setDefined(['hostname', 'host']) - // this outputs the following generic deprecation message: - // The option "hostname" is deprecated. - ->setDeprecated('hostname') - // you can also pass a custom deprecation message - ->setDeprecated('hostname', 'The option "hostname" is deprecated, use "host" instead.') + // this outputs the following generic deprecation message: + // Since acme/package 1.2: The option "hostname" is deprecated. + ->setDeprecated('hostname', 'acme/package', '1.2') + + // you can also pass a custom deprecation message (%name% placeholder is available) + ->setDeprecated( + 'hostname', + 'acme/package', + '1.2', + 'The option "hostname" is deprecated, use "host" instead.' + ) ; .. note:: @@ -756,7 +769,7 @@ the option:: ->setDefault('encryption', null) ->setDefault('port', null) ->setAllowedTypes('port', ['null', 'int']) - ->setDeprecated('port', function (Options $options, $value) { + ->setDeprecated('port', 'acme/package', '1.2', function (Options $options, $value) { if (null === $value) { return 'Passing "null" to option "port" is deprecated, pass an integer instead.'; } diff --git a/service_container/alias_private.rst b/service_container/alias_private.rst index ffde46bfce6..c97fe5c82db 100644 --- a/service_container/alias_private.rst +++ b/service_container/alias_private.rst @@ -160,6 +160,12 @@ This means that when using the container directly, you can access the Deprecating Service Aliases ~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. versionadded:: 5.1 + + The ``package`` and ``version`` options were introduced in Symfony 5.1. + Prior to 5.1, you had to use ``deprecated: true`` or + ``deprecated: 'Custom message'``. + If you decide to deprecate the use of a service alias (because it is outdated or you decided not to maintain it anymore), you can deprecate its definition: @@ -170,11 +176,17 @@ or you decided not to maintain it anymore), you can deprecate its definition: app.mailer: alias: '@App\Mail\PhpMailer' - # this will display a generic deprecation message... - deprecated: true + # this outputs the following generic deprecation message: + # Since acme/package 1.2: The "app.mailer" service is deprecated. You should stop using it, as it will be removed in the future + deprecated: + package: 'acme/package' + version: '1.2' - # ...but you can also define a custom deprecation message - deprecated: 'The "%alias_id%" alias is deprecated. Do not use it anymore.' + # you can also define a custom deprecation message (%sevice_id%/%alias_id% placeholder is available) + deprecated: + package: 'acme/package' + version: '1.2' + message: 'The "%alias_id%" alias is deprecated. Do not use it anymore.' .. code-block:: xml @@ -185,11 +197,14 @@ or you decided not to maintain it anymore), you can deprecate its definition: - - - - - The "%alias_id%" service alias is deprecated. Don't use it anymore. + + + + + + The "%alias_id%" service alias is deprecated. Don't use it anymore. + @@ -199,12 +214,14 @@ or you decided not to maintain it anymore), you can deprecate its definition: $container ->setAlias('app.mailer', 'App\Mail\PhpMailer') - // this will display a generic deprecation message... - ->setDeprecated(true) + // this outputs the following generic deprecation message: + // Since acme/package 1.2: The "app.mailer" service is deprecated. You should stop using it, as it will be removed in the future + ->setDeprecated('acme/package', '1.2') - // ...but you can also define a custom deprecation message + // you can also define a custom deprecation message (%sevice_id%/%alias_id% placeholder is available) ->setDeprecated( - true, + 'acme/package', + '1.2', 'The "%alias_id%" service alias is deprecated. Don\'t use it anymore.' ) ;