forked from https://github.com/symfony/symfony
76d3589a44
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 | https://github.com/symfony/symfony-docs/pull/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
-------
|
||
|---|---|---|
| .composer | ||
| .github | ||
| src/Symfony | ||
| .editorconfig | ||
| .gitignore | ||
| .php_cs.dist | ||
| .travis.yml | ||
| appveyor.yml | ||
| CHANGELOG-4.0.md | ||
| CHANGELOG-4.1.md | ||
| composer.json | ||
| CONTRIBUTING.md | ||
| CONTRIBUTORS.md | ||
| LICENSE | ||
| link | ||
| phpunit | ||
| phpunit.xml.dist | ||
| README.md | ||
| UPGRADE-4.0.md | ||
| UPGRADE-4.1.md | ||
| UPGRADE-4.2.md | ||
| UPGRADE-5.0.md | ||
Symfony is a PHP framework for web applications and a set of reusable PHP components. Symfony is used by thousands of web applications (including BlaBlaCar.com and Spotify.com) and most of the popular PHP projects (including Drupal and Magento).
Installation
- Install Symfony with Composer (see requirements details).
- Symfony follows the semantic versioning strictly, publishes "Long Term Support" (LTS) versions and has a release process that is predictable and business-friendly.
Documentation
- Read the Getting Started guide if you are new to Symfony.
- Try the Symfony Demo application to learn Symfony in practice.
- Master Symfony with the Guides and Tutorials, the Components docs and the Best Practices reference.
Community
- Join the Symfony Community and meet other members at the Symfony events.
- Get Symfony support on Stack Overflow, Slack, IRC, etc.
- Follow us on GitHub, Twitter and Facebook.
- Read our Code of Conduct and meet the CARE Team
Contributing
Symfony is an Open Source, community-driven project with thousands of contributors. Join them contributing code or contributing documentation.
Security Issues
If you discover a security vulnerability within Symfony, please follow our disclosure procedure.
About Us
Symfony development is sponsored by SensioLabs, led by the Symfony Core Team and supported by Symfony contributors.