…r (webmozart)

This PR was merged into the 2.6-dev branch.

Discussion
----------

[OptionsResolver] Merged Options class into OptionsResolver

| Q             | A
| ------------- | ---
| Bug fix?      | yes
| New feature?  | no
| BC breaks?    | yes
| Deprecations? | yes
| Tests pass?   | yes
| Fixed tickets | #4500, #9174, #10585, #10202, #11020, makes #7979+#10616 obsolete
| License       | MIT
| Doc PR        | symfony/symfony-docs#4159

#11716 was reverted as preparation of this PR (453882c).

The Options class was merged into OptionsResolver. This made it possible to fix several tickets, as indicated above.

**Usage**

See [the updated documentation](https://github.com/webmozart/symfony-docs/blob/issue11705/components/options_resolver.rst).

**Bug Fixes**

Previously, the options weren't validated before the normalizers were called. As a result, the normalizers had to perform validation again:

```php
$resolver->setAllowedTypes(array(
    'choices' => 'array',
));
$resolver->setNormalizers(array(
    'choices' => function (Options $options, $value) {
         array_merge($options['choices'], ...);
    },
));

// fatal error
$resolver->resolve(array('choices' => 'foobar'));
```

This is fixed now.

**BC Breaks**

The `array` type hint was removed from `setRequired()`, `setAllowedValues()`, `addAllowedValues()`, `setAllowedTypes()` and `addAllowedTypes()`. If anybody implemented `OptionsResolverInterface`, they must adapt their code.

The Options class was turned into an interface extending ArrayAccess and Countable. Anybody instantiating Options directly should instantiate OptionsResolver instead. Anybody using any of the methods available in Options (`get()`, `has()`) should use the ArrayAccess interface instead.

Normalizers are not called anymore for undefined options (#9174). People need to set a default value if they want a normalizer to be executed independent of the options passed to `resolve()`.

**Deprecations**

OptionsResolverInterface was deprecated and will be removed in 3.0. OptionsResolver instances are not supposed to be shared between classes, hence an interface does not make sense.

Several other methods were deprecated. See the CHANGELOG and UPGRADE-2.6 files for information.

**Todo**

- [x] Fix PHPDoc
- [x] Adapt CHANGELOG/UPGRADE
- [x] Adapt documentation
- [x] Deprecate OptionsResolver[Interface]

Commits
-------

642c119 [OptionsResolver] Merged Options class into OptionsResolver