…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