8000 minor #13521 [OptionsResolver][Config][DI] Added package and version … · symfony/symfony-docs@77f41f0 · GitHub
[go: up one dir, main page]
Skip to content

Commit 77f41f0

Browse files
javiereguiluzjaviereguiluz
committed
minor #13521 [OptionsResolver][Config][DI] Added package and version to deprecation features (wouterj)
This PR was submitted for the master branch but it was merged into the 5.1 branch instead. Discussion ---------- [OptionsResolver][Config][DI] Added package and version to deprecation features Fixes #13465, Fixes #13508, Fixes #13470 Commits ------- 82a44b2 [OptionsResolver][Config][DI] Added package and version to deprecation features
2 parents 635370d + 82a44b2 commit 77f41f0

File tree

3 files changed

+63
-22
lines changed

3 files changed

+63
-22
lines changed

‎components/config/definition.rst

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -435,6 +435,13 @@ The following example shows these methods in practice::
435435
Deprecating the Option
436436
----------------------
437437

438+
.. versionadded:: 5.1
439+
440+
The signature of the ``setDeprecated()`` method changed from
441+
``setDeprecated(?string $message)`` to
442+
``setDeprecated(string $package, string $version, ?string $message)``
443+
in Symfony 5.1.
444+
438445
You can deprecate options using the
439446
:method:`Symfony\\Component\\Config\\Definition\\Builder\\NodeDefinition::setDeprecated`
440447
method::
@@ -443,11 +450,15 @@ method::
443450
->children()
444451
->integerNode('old_option')
445452
// this outputs the following generic deprecation message:
446-
// The child node "old_option" at path "..." is deprecated.
447-
->setDeprecated()
453+
// Since acme/package 1.2: The child node "old_option" at path "..." is deprecated.
454+
->setDeprecated('acme/package', '1.2')
448455

449456
// you can also pass a custom deprecation message (%node% and %path% placeholders are available):
450-
->setDeprecated('The "%node%" option is deprecated. Use "new_config_option" instead.')
457+
->setDeprecated(
458+
'acme/package',
459+
'1.2',
460+
'The "%node%" option is deprecated. Use "new_config_option" instead.'
461+
)
451462
->end()
452463
->end()
453464
;

‎components/options_resolver.rst

Lines changed: 19 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -720,18 +720,31 @@ In same way, parent options can access to the nested options as normal arrays::
720720
Deprecating the Option
721721
~~~~~~~~~~~~~~~~~~~~~~
722722

723+
.. versionadded:: 5.1
724+
725+
The signature of the ``setDeprecated()`` method changed from
726+
``setDeprecated(string $option, ?string $message)`` to
727+
``setDeprecated(string $option, string $package, string $version, ?string $message)``
728+
in Symfony 5.1.
729+
723730
Once an option is outdated or you decided not to maintain it anymore, you can
724731
deprecate it using the :method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::setDeprecated`
725732
method::
726733

727734
$resolver
728735
->setDefined(['hostname', 'host'])
729-
// this outputs the following generic deprecation message:
730-
// The option "hostname" is deprecated.
731-
->setDeprecated('hostname')
732736

733-
// you can also pass a custom deprecation message
734-
->setDeprecated('hostname', 'The option "hostname" is deprecated, use "host" instead.')
737+
// this outputs the following generic deprecation message:
738+
// Since acme/package 1.2: The option "hostname" is deprecated.
739+
->setDeprecated('hostname', 'acme/package', '1.2')
740+
741+
// you can also pass a custom deprecation message (%name% placeholder is available)
742+
->setDeprecated(
743+
'hostname',
744+
'acme/package',
745+
'1.2',
746+
'The option "hostname" is deprecated, use "host" instead.'
747+
)
735748
;
736749

737750
.. note::
@@ -756,7 +769,7 @@ the option::
756769
->setDefault('encryption', null)
757770
->setDefault('port', null)
758771
->setAllowedTypes('port', ['null', 'int'])
759-
->setDeprecated('port', function (Options $options, $value) {
772+
->setDeprecated('port', 'acme/package', '1.2', function (Options $options, $value) {
760773
if (null === $value) {
761774
return 'Passing "null" to option "port" is deprecated, pass an integer instead.';
762775
}

‎service_container/alias_private.rst

Lines changed: 30 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -160,6 +160,12 @@ This means that when using the container directly, you can access the
160160
Deprecating Service Aliases
161161
~~~~~~~~~~~~~~~~~~~~~~~~~~~
162162

163+
.. versionadded:: 5.1
164+
165+
The ``package`` and ``version`` options were introduced in Symfony 5.1.
166+
Prior to 5.1, you had to use ``deprecated: true`` or
167+
``deprecated: 'Custom message'``.
168+
163169
If you decide to deprecate the use of a service alias (because it is outdated
164170
or you decided not to maintain it anymore), you can deprecate its definition:
165171

@@ -170,11 +176,17 @@ or you decided not to maintain it anymore), you can deprecate its definition:
170176
app.mailer:
171177
alias: '@App\Mail\PhpMailer'
172178
173-
# this will display a generic deprecation message...
174-
deprecated: true
179+
# this outputs the following generic deprecation message:
180+
# Since acme/package 1.2: The "app.mailer" service is deprecated. You should stop using it, as it will be removed in the future
181+
deprecated:
182+
package: 'acme/package'
183+
version: '1.2'
175184
176-
# ...but you can also define a custom deprecation message
177-
deprecated: 'The "%alias_id%" alias is deprecated. Do not use it anymore.'
185+
# you can also define a custom deprecation message (%sevice_id%/%alias_id% placeholder is available)
186+
deprecated:
187+
package: 'acme/package'
188+
version: '1.2'
189+
message: 'The "%alias_id%" alias is deprecated. Do not use it anymore.'
178190
179191
.. code-block:: xml
180192
@@ -185,11 +197,14 @@ or you decided not to maintain it anymore), you can deprecate its definition:
185197
186198
<services>
187199
<service id="app.mailer" alias="App\Mail\PhpMailer">
188-
<!-- this will display a generic deprecation message... -->
189-
<deprecated/>
190-
191-
<!-- ...but you can also define a custom deprecation message -->
192-
<deprecated>The "%alias_id%" service alias is deprecated. Don't use it anymore.</deprecated>
200+
<!-- this outputs the following generic deprecation message:
201+
Since acme/package 1.2: The "app.mailer" service is deprecated. You should stop using it, as it will be removed in the future -->
202+
<deprecated package="acme/package" version="1.2"/>
203+
204+
<!-- you can also define a custom deprecation message (%sevice_id%/%alias_id% placeholder is available) -->
205+
<deprecated package="acme/package" version="1.2">
206+
The "%alias_id%" service alias is deprecated. Don't use it anymore.
207+
</deprecated>
193208
</service>
194209
</services>
195210
</container>
@@ -199,12 +214,14 @@ or you decided not to maintain it anymore), you can deprecate its definition:
199214
$container
200215
->setAlias('app.mailer', 'App\Mail\PhpMailer')
201216
202-
// this will display a generic deprecation message...
203-
->setDeprecated(true)
217+
// this outputs the following generic deprecation message:
218+
// Since acme/package 1.2: The "app.mailer" service is deprecated. You should stop using it, as it will be removed in the future
219+
->setDeprecated('acme/package', '1.2')
204220
205-
// ...but you can also define a custom deprecation message
221+
// you can also define a custom deprecation message (%sevice_id%/%alias_id% placeholder is available)
206222
->setDeprecated(
207-
true,
223+
'acme/package',
224+
'1.2',
208225
'The "%alias_id%" service alias is deprecated. Don\'t use it anymore.'
209226
)
210227
;

0 commit comments

Comments
 (0)
0