[OptionsResolver] Introduce ability to deprecate options, allowed types and values #27277

yceruto · 2018-05-15T15:31:38Z

Q	A
Branch?	master
Bug fix?	no
New feature?	yes
BC breaks?	no
Deprecations?	no
Tests pass?	yes
Fixed tickets	#27216
License	MIT
Doc PR	symfony/symfony-docs#9859

Deprecating an option

$resolver = (new OptionsResolver())
    ->setDefined(['foo', 'bar'])
    ->setDeprecated('foo')
;
$resolver->resolve(['foo' => 'baz']); // PHP Deprecated: The option "foo" is deprecated.

With custom message:

$resolver = (new OptionsResolver())
    ->setDefined('foo')
    ->setDefault('bar', function (Options $options) {
        return $options['foo'];
    })
    ->setDeprecated('foo', 'The option "foo" is deprecated, use "bar" option instead.')
;
$resolver->resolve(['foo' => 'baz']); // PHP Deprecated: The option "foo" is deprecated, use "bar" option instead.
$resolver->resolve(['bar' => 'baz']); // OK.

Deprecating allowed types

$resolver = (new OptionsResolver())
    ->setDefault('type', null)
    ->setAllowedTypes('type', ['null', 'string', FormTypeInterface::class])
    ->setDeprecated('type', function ($value) {
        if ($value instanceof FormTypeInterface) {
            return sprintf('Passing an instance of "%s" to option "type" is deprecated, pass its FQCN instead.', FormTypeInterface::class);
        }
    })
;
$resolver->resolve(['type' => new ChoiceType()]); // PHP Deprecated: Passing an instance of "Symfony\Component\Form\FormTypeInterface" to option "type" is deprecated, pass its FQCN instead.
$resolver->resolve(['type' => ChoiceType::class]); // OK.

The closure is invoked when resolve() is called. The closure must return a string (the deprecation message) or an empty string to ignore the option deprecation.

Multiple types and normalizer:

$resolver = (new OptionsResolver())
    ->setDefault('percent', 0.0)
    ->setAllowedTypes('percent', ['null', 'int', 'float'])
    ->setDeprecated('percent', function ($value) {
        if (null === $value) {
            return 'Passing "null" to option "percent" is deprecated, pass a float number instead.';
        }

        if (is_int($value)) {
            return sprintf('Passing an integer "%d" to option "percent" is deprecated, pass a float number instead.', $value);
        }
    })
    ->setNormalizer('percent', function (Options $options, $value) {
        return (float) $value;
    })
;
$resolver->resolve(['percent' => null]); // PHP Deprecated: Passing "null" to option "percent" is deprecated, pass a float number instead.
$resolver->resolve(['percent' => 20]); // PHP Deprecated: Passing an integer "20" to option "percent" is deprecated, pass a float number instead.
$resolver->resolve(['percent' => 20.0]); // OK.

The parameter passed to the closure is the value of the option after validating it and before normalizing it.

Deprecating allowed values

$resolver = (new OptionsResolver())
    ->setDefault('percent', 0.0)
    ->setAllowedTypes('percent', 'float')
    ->setDeprecated('percent', function ($value) {
        if ($value < 0) {
            return 'Passing a number less than 0 to option "percent" is deprecated.';
        }
    })
;
$resolver->resolve(['percent' => -50.0]); // PHP Deprecated: Passing a number less than 0 to option "percent" is deprecated.

yceruto · 2018-05-15T15:49:39Z

~~fabbot.io failure is unrelated, should I fix it here?~~ already fixed after rebased.

ro0NL · 2018-05-16T08:49:47Z

The "Deprecating allowed values" is kinda the same example as "Deprecating allowed types".. no?

yceruto · 2018-05-16T11:20:23Z

The "Deprecating allowed values" is kinda the same example as "Deprecating allowed types".. no?

Yes, same approach: a closure function that returns a string or not depending on the given value. However in "Deprecating allowed values" example you aren't deprecating the value type at all but just a range.

src/Symfony/Component/OptionsResolver/OptionsResolver.php

src/Symfony/Component/OptionsResolver/Tests/OptionsResolverTest.php

yceruto · 2018-05-30T12:53:39Z

@fabpot comments addressed, very appreciated your review, thanks.

yceruto · 2018-05-30T13:24:42Z

I just changed the exception class here InvalidOptionsException instead of InvalidArgumentException.

nicolas-grekas · 2018-06-19T12:56:40Z

Thank you @yceruto.

…ns, allowed types and values (yceruto) This PR was merged into the 4.2-dev branch. Discussion ---------- [OptionsResolver] Introduce ability to deprecate options, allowed types and values | Q | A | ------------- | --- | Branch? | master | Bug fix? | no | New feature? | yes | BC breaks? | no | Deprecations? | no | Tests pass? | yes | Fixed tickets | #27216 | License | MIT | Doc PR | symfony/symfony-docs#9859 **Deprecating an option** ```php $resolver = (new OptionsResolver()) ->setDefined(['foo', 'bar']) ->setDeprecated('foo') ; $resolver->resolve(['foo' => 'baz']); // PHP Deprecated: The option "foo" is deprecated. ``` With custom message: ```php $resolver = (new OptionsResolver()) ->setDefined('foo') ->setDefault('bar', function (Options $options) { return $options['foo']; }) ->setDeprecated('foo', 'The option "foo" is deprecated, use "bar" option instead.') ; $resolver->resolve(['foo' => 'baz']); // PHP Deprecated: The option "foo" is deprecated, use "bar" option instead. $resolver->resolve(['bar' => 'baz']); // OK. ``` **Deprecating allowed types** ```php $resolver = (new OptionsResolver()) ->setDefault('type', null) ->setAllowedTypes('type', ['null', 'string', FormTypeInterface::class]) ->setDeprecated('type', function ($value) { if ($value instanceof FormTypeInterface) { return sprintf('Passing an instance of "%s" to option "type" is deprecated, pass its FQCN instead.', FormTypeInterface::class); } }) ; $resolver->resolve(['type' => new ChoiceType()]); // PHP Deprecated: Passing an instance of "Symfony\Component\Form\FormTypeInterface" to option "type" is deprecated, pass its FQCN instead. $resolver->resolve(['type' => ChoiceType::class]); // OK. ``` The closure is invoked when `resolve()` is called. The closure must return a string (the deprecation message) or an empty string to ignore the option deprecation. Multiple types and normalizer: ```php $resolver = (new OptionsResolver()) ->setDefault('percent', 0.0) ->setAllowedTypes('percent', ['null', 'int', 'float']) ->setDeprecated('percent', function ($value) { if (null === $value) { return 'Passing "null" to option "percent" is deprecated, pass a float number instead.'; } if (is_int($value)) { return sprintf('Passing an integer "%d" to option "percent" is deprecated, pass a float number instead.', $value); } }) ->setNormalizer('percent', function (Options $options, $value) { return (float) $value; }) ; $resolver->resolve(['percent' => null]); // PHP Deprecated: Passing "null" to option "percent" is deprecated, pass a float number instead. $resolver->resolve(['percent' => 20]); // PHP Deprecated: Passing an integer "20" to option "percent" is deprecated, pass a float number instead. $resolver->resolve(['percent' => 20.0]); // OK. ``` The parameter passed to the closure is the value of the option after validating it and before normalizing it. **Deprecating allowed values** ```php $resolver = (new OptionsResolver()) ->setDefault('percent', 0.0) ->setAllowedTypes('percent', 'float') ->setDeprecated('percent', function ($value) { if ($value < 0) { return 'Passing a number less than 0 to option "percent" is deprecated.'; } }) ; $resolver->resolve(['percent' => -50.0]); // PHP Deprecated: Passing a number less than 0 to option "percent" is deprecated. ``` Commits ------- f8746ce Add ability to deprecate options

This PR was merged into the master branch. Discussion ---------- [OptionsResolver] Document setDeprecated method Documenting feature symfony/symfony#27277. Commits ------- afa5e54 Document setDeprecated method from OptionsResolver component

…tion on debug:form command (yceruto) This PR was merged into the 4.2-dev branch. Discussion ---------- [Form][OptionsResolver] Show deprecated options definition on debug:form command | Q | A | ------------- | --- | Branch? | master | Bug fix? | no | New feature? | yes | BC breaks? | no | Deprecations? | no | Tests pass? | yes | Fixed tickets | - | License | MIT | Doc PR | - Next move after symfony/symfony#27277. It will look like this: Use `--show-deprecated` option to show form types with deprecated options (example): ![debug_types_with_deprecated_options](https://user-images.githubusercontent.com/2028198/41823977-970c7c98-77d6-11e8-9e97-30dcedc316ac.png) Use `--show-deprecated` option to show deprecated options of the given form type (example): ![debug_deprecated_options_from_type](https://user-images.githubusercontent.com/2028198/41823980-a4d6bd8e-77d6-11e8-95ed-39926ffd6235.png) Deprecated option (example): ![debug_deprecated_option_text](https://user-images.githubusercontent.com/2028198/41689091-04e6b7dc-74bd-11e8-87d0-90729eac4bb3.png) ![debug_deprecated_option_json](https://user-images.githubusercontent.com/2028198/41689105-142b5c5c-74bd-11e8-9232-1f30237bcf69.png) Commits ------- 87c209d741 Show deprecated options definition on debug:form command

…tion on debug:form command (yceruto) This PR was merged into the 4.2-dev branch. Discussion ---------- [Form][OptionsResolver] Show deprecated options definition on debug:form command | Q | A | ------------- | --- | Branch? | master | Bug fix? | no | New feature? | yes | BC breaks? | no | Deprecations? | no | Tests pass? | yes | Fixed tickets | - | License | MIT | Doc PR | - Next move after #27277. It will look like this: Use `--show-deprecated` option to show form types with deprecated options (example): ![debug_types_with_deprecated_options](https://user-images.githubusercontent.com/2028198/41823977-970c7c98-77d6-11e8-9e97-30dcedc316ac.png) Use `--show-deprecated` option to show deprecated options of the given form type (example): ![debug_deprecated_options_from_type](https://user-images.githubusercontent.com/2028198/41823980-a4d6bd8e-77d6-11e8-95ed-39926ffd6235.png) Deprecated option (example): ![debug_deprecated_option_text](https://user-images.githubusercontent.com/2028198/41689091-04e6b7dc-74bd-11e8-87d0-90729eac4bb3.png) ![debug_deprecated_option_json](https://user-images.githubusercontent.com/2028198/41689105-142b5c5c-74bd-11e8-9232-1f30237bcf69.png) Commits ------- 87c209d Show deprecated options definition on debug:form command

carsonbot added Status: Needs Review OptionsResolver Feature labels May 15, 2018

yceruto mentioned this pull request May 15, 2018

[RFC][OptionsResolver] Add ability to deprecate options #27216

Closed

yceruto force-pushed the options_resolver_deprecated_option branch from 381c953 to 3b7280e Compare May 15, 2018 15:35

yceruto force-pushed the options_resolver_deprecated_option branch from 3b7280e to 981c2bf Compare May 15, 2018 15:57

yceruto force-pushed the options_resolver_deprecated_option branch 2 times, most recently from 0e6ff64 to b47b6b7 Compare May 18, 2018 12:15

nicolas-grekas added this to the next milestone May 18, 2018

yceruto force-pushed the options_resolver_deprecated_option branch from b47b6b7 to e112140 Compare May 23, 2018 19:04

fabpot requested changes May 30, 2018

View reviewed changes

carsonbot added Status: Needs Work and removed Status: Needs Review labels May 30, 2018

yceruto force-pushed the options_resolver_deprecated_option branch from e112140 to bbed8b3 Compare May 30, 2018 12:47

carsonbot removed the Status: Needs Work label May 30, 2018

fabpot approved these changes May 30, 2018

View reviewed changes

carsonbot added the Status: Reviewed label May 30, 2018

yceruto force-pushed the options_resolver_deprecated_option branch from bbed8b3 to 9beb4ab Compare May 30, 2018 13:10

yceruto mentioned this pull request May 31, 2018

[OptionsResolver] Document setDeprecated method symfony/symfony-docs#9859

Merged

Add ability to deprecate options

f8746ce

yceruto force-pushed the options_resolver_deprecated_option branch from 9beb4ab to f8746ce Compare May 31, 2018 11:28

nicolas-grekas approved these changes Jun 19, 2018

View reviewed changes

nicolas-grekas merged commit f8746ce into symfony:master Jun 19, 2018

yceruto deleted the options_resolver_deprecated_option branch June 20, 2018 12:56

yceruto mentioned this pull request Jun 20, 2018

[Form][OptionsResolver] Show deprecated options definition on debug:form command #27667

Merged

yceruto mentioned this pull request Oct 4, 2018

[Form] deprecate some options for single_text widgets #28721

Merged

ro0NL mentioned this pull request Oct 13, 2018

[OptionsResolver] Options not provided by user triggers deprecation #28848

Closed

nicolas-grekas modified the milestones: next, 4.2 Nov 1, 2018

This was referenced Nov 3, 2018

Release v4.2.0-BETA1 #29072

Closed

Release v4.2.0-BETA1 #29073

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[OptionsResolver] Introduce ability to deprecate options, allowed types and values #27277

[OptionsResolver] Introduce ability to deprecate options, allowed types and values #27277

yceruto commented May 15, 2018 •

edited

Loading

yceruto commented May 15, 2018 •

edited

Loading

ro0NL commented May 16, 2018

yceruto commented May 16, 2018 •

edited

Loading

yceruto commented May 30, 2018

yceruto commented May 30, 2018

nicolas-grekas commented Jun 19, 2018

[OptionsResolver] Introduce ability to deprecate options, allowed types and values #27277

[OptionsResolver] Introduce ability to deprecate options, allowed types and values #27277

Conversation

yceruto commented May 15, 2018 • edited Loading

yceruto commented May 15, 2018 • edited Loading

ro0NL commented May 16, 2018

yceruto commented May 16, 2018 • edited Loading

yceruto commented May 30, 2018

yceruto commented May 30, 2018

nicolas-grekas commented Jun 19, 2018

yceruto commented May 15, 2018 •

edited

Loading

yceruto commented May 15, 2018 •

edited

Loading

yceruto commented May 16, 2018 •

edited

Loading