8000 bug #12156 [OptionsResolver] Merged Options class into OptionsResolve… · symfony/symfony@8838143 · GitHub
[go: up one dir, main page]
Skip to content

Commit 8838143

Browse files
webmozartwebmozart
committed
bug #12156 [OptionsResolver] Merged Options class into OptionsResolver (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
2 parents 22d3df8 + 642c119 commit 8838143

15 files changed

+2783
-1026
lines changed

‎UPGRADE-2.6.md

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -128,3 +128,184 @@ HttpFoundation
128128
- You would need to migrate the table manually if you want to keep session information of your users.
129129
- You could use `PdoSessionHandler::createTable` to initialize a correctly defined table depending on
130130
the used database vendor.
131+
132+
OptionsResolver
133+
---------------
134+
135+
* The "array" type hint was removed from the `OptionsResolverInterface` methods
136+
`setRequired()`, `setAllowedValues()`, `addAllowedValues()`,
137+
`setAllowedTypes()` and `addAllowedTypes()`. You must remove the type hint
138+
from your implementations.
139+
140+
* The interface `OptionsResolverInterface` was deprecated, since
141+
`OptionsResolver` instances are not supposed to be shared between classes.
142+
You should type hint against `OptionsResolver` instead.
143+
144+
Before:
145+
146+
```php
147+
protected function configureOptions(OptionsResolverInterface $resolver)
148+
{
149+
// ...
150+
}
151+
```
152+
153+
After:
154+
155+
```php
156+
protected function configureOptions(OptionsResolver $resolver)
157+
{
158+
// ...
159+
}
160+
```
161+
162+
* `OptionsResolver::isRequired()` now returns `true` if a required option has
163+
a default value set. The new method `isMissing()` exhibits the old
164+
functionality of `isRequired()`.
165+
166+
Before:
167+
168+
```php
169+
$resolver->setRequired(array('port'));
170+
171+
$resolver->isRequired('port');
172+
// => true
173+
174+
$resolver->setDefaults(array('port' => 25));
175+
176+
$resolver->isRequired('port');
177+
// => false
178+
```
179+
180+
After:
181+
182+
```php
183+
$resolver->setRequired(array('port'));
184+
185+
$resolver->isRequired('port');
186+
// => true
187+
$resolver->isMissing('port');
188+
// => true
189+
190+
$resolver->setDefaults(array('port' => 25));
191+
192+
$resolver->isRequired('port');
193+
// => true
194+
$resolver->isMissing('port');
195+
// => false
196+
```
197+
198+
* `OptionsResolver::replaceDefaults()` was deprecated. Use `clear()` and
199+
`setDefaults()` instead.
200+
201+
Before:
202+
203+
```php
204+
$resolver->replaceDefaults(array(
205+
'port' => 25,
206+
));
207+
```
208+
209+
After:
210+
211+
```php
212+
$resolver->clear();
213+
$resolver->setDefaults(array(
214+
'port' => 25,
215+
));
216+
```
217+
218+
* `OptionsResolver::setOptional()` was deprecated. Use `setDefined()` instead.
219+
220+
Before:
221+
222+
```php
223+
$resolver->setOptional(array('port'));
224+
```
225+
226+
After:
227+
228+
```php
229+
$resolver->setDefined('port');
230+
```
231+
232+
* `OptionsResolver::isKnown()` was deprecated. Use `isDefined()` instead.
233+
234+
Before:
235+
236+
```php
237+
if ($resolver->isKnown('port')) {
238+
// ...
239+
}
240+
```
241+
242+
After:
243+
244+
```php
245+
if ($resolver->isDefined('port')) {
246+
// ...
247+
}
248+
```
249+
250+
* The methods `setAllowedValues()`, `addAllowedValues()`, `setAllowedTypes()`
251+
and `addAllowedTypes()` were changed to modify one option at a time instead
252+
of batch processing options. The old API exists for backwards compatibility,
253+
but will be removed in Symfony 3.0.
254+
255+
Before:
256+
257+
```php
258+
$resolver->setAllowedValues(array(
259+
'method' => array('POST', 'GET'),
260+
));
261+
```
262+
263+
After:
264+
265+
```php
266+
$resolver->setAllowedValues('method', array('POST', 'GET'));
267+
```
268+
269+
* The class `Options` was merged into `OptionsResolver`. If you instantiated
270+
this class manually, you should instantiate `OptionsResolver` now.
271+
`Options` is now a marker interface implemented by `OptionsResolver`.
272+
273+
Before:
274+
275+
```php
276+
$options = new Options();
277+
```
278+
279+
After:
280+
281+
```php
282+
$resolver = new OptionsResolver();
283+
```
284+
285+
* Normalizers for defined but unset options are not executed anymore. If you
286+
want to have them executed, you should define a default value.
287+
288+
Before:
289+
290+
```php
291+
$resolver->setOptional(array('port'));
292+
$resolver->setNormalizers(array(
293+
'port' => function ($options, $value) {
294+
// return normalized value
295+
}
296+
));
297+
298+
$options = $resolver->resolve($options);
299+
```
300+
301+
After:
302+
303+
```php
304+
$resolver->setDefault('port', null);
305+
$resolver->setNormalizer('port', function ($options, $value) {
306+
// return normalized value
307+
});
308+
309+
$options = $resolver->resolve($options);
310+
```
311+

‎src/Symfony/Component/OptionsResolver/CHANGELOG.md

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
CHANGELOG
2+
=========
3+
4+
2.6.0
5+
-----
6+
7+
* deprecated OptionsResolverInterface
8+
* [BC BREAK] removed "array" type hint from OptionsResolverInterface methods
9+
setRequired(), setAllowedValues(), addAllowedValues(), setAllowedTypes() and
10+
addAllowedTypes()
11+
* added OptionsResolver::setDefault()
12+
* added OptionsResolver::hasDefault()
13+
* added OptionsResolver::setNormalizer()
14+
* added OptionsResolver::isRequired()
15+
* added OptionsResolver::getRequiredOptions()
16+
* added OptionsResolver::isMissing()
17+
* added OptionsResolver::getMissingOptions()
18+
* added OptionsResolver::setDefined()
19+
* added OptionsResolver::isDefined()
20+
* added OptionsResolver::getDefinedOptions()
21+
* added OptionsResolver::remove()
22+
* added OptionsResolver::clear()
23+
* deprecated OptionsResolver::replaceDefaults()
24+
* deprecated OptionsResolver::setOptional() in favor of setDefined()
25+
* deprecated OptionsResolver::isKnown() in favor of isDefined()
26+
* [BC BREAK] OptionsResolver::isRequired() returns true now if a required
27+
option has a default value set
28+
* [BC BREAK] merged Options into OptionsResolver and turned Options into an
29+
interface
30+
* deprecated Options::overload() (now in OptionsResolver)
31+
* deprecated Options::set() (now in OptionsResolver)
32+
* deprecated Options::get() (now in OptionsResolver)
33+
* deprecated Options::has() (now in OptionsResolver)
34+
* deprecated Options::replace() (now in OptionsResolver)
35+
* [BC BREAK] Options::get() (now in OptionsResolver) can only be used within
36+
lazy option/normalizer closures now
37+
* [BC BREAK] removed Traversable interface from Options since using within
38+
lazy option/normalizer closures resulted in exceptions
39+
* [BC BREAK] removed Options::all() since using within lazy option/normalizer
40+
closures resulted in exceptions
41+
* [BC BREAK] OptionDefinitionException now extends LogicException instead of
42+
RuntimeException
43+
* [BC BREAK] normalizers are not executed anymore for unset options
44+
* normalizers are executed after validating the options now

‎src/Symfony/Component/OptionsResolver/Exception/AccessException.php

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
<?php
2+
3+
/*
4+
* This file is part of the Symfony package.
5+
*
6+
* (c) Fabien Potencier <fabien@symfony.com>
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*/
11+
12+
namespace Symfony\Component\OptionsResolver\Exception;
13+
14+
/**
15+
* Thrown when trying to read an option outside of or write it inside of
16+
* {@link Options::resolve()}.
17+
*
18+
* @author Bernhard Schussek <bschussek@gmail.com>
19+
*/
20+
class AccessException extends \LogicException implements ExceptionInterface
21+
{
22+
}

‎src/Symfony/Component/OptionsResolver/Exception/InvalidArgumentException.php

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
<?php
2+
3+
/*
4+
* This file is part of the Symfony package.
5+
*
6+
* (c) Fabien Potencier <fabien@symfony.com>
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*/
11+
12+
namespace Symfony\Component\OptionsResolver\Exception;
13+
14+
/**
15+
* Thrown when an argument is invalid.
16+
*
17+
* @author Bernhard Schussek <bschussek@gmail.com>
18+
*/
19+
class InvalidArgumentException extends \InvalidArgumentException implements ExceptionInterface
20+
{
21+
}

‎src/Symfony/Component/OptionsResolver/Exception/InvalidOptionsException.php

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,12 @@
1212
namespace Symfony\Component\OptionsResolver\Exception;
1313

1414
/**
15-
* Exception thrown when an invalid option is passed.
15+
* Thrown when the value of an option does not match its validation rules.
16+
*
17+
* You should make sure a valid value is passed to the option.
1618
*
1719
* @author Bernhard Schussek <bschussek@gmail.com>
1820
*/
19-
class InvalidOptionsException extends \InvalidArgumentException implements ExceptionInterface
21+
class InvalidOptionsException extends InvalidArgumentException
2022
{
2123
}

‎src/Symfony/Component/OptionsResolver/Exception/MissingOptionsException.php

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,10 @@
1414
/**
1515
* Exception thrown when a required option is missing.
1616
*
17+
* Add the option to the passed options array.
18+
*
1719
* @author Bernhard Schussek <bschussek@gmail.com>
1820
*/
19-
class MissingOptionsException extends \InvalidArgumentException implements ExceptionInterface
21+
class MissingOptionsException extends InvalidArgumentException
2022
{
2123
}

‎src/Symfony/Component/OptionsResolver/Exception/OptionDefinitionException.php

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,10 @@
1212
namespace Symfony\Component\OptionsResolver\Exception;
1313

1414
/**
15-
* Thrown when an option definition is invalid.
15+
* Thrown when two lazy options have a cyclic dependency.
1616
*
1717
* @author Bernhard Schussek <bschussek@gmail.com>
1818
*/
19-
class OptionDefinitionException extends \RuntimeException implements ExceptionInterface
19+
class OptionDefinitionException extends \LogicException implements ExceptionInterface
2020
{
2121
}

‎src/Symfony/Component/OptionsResolver/Exception/UndefinedOptionsException.php

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
<?php
2+
3+
/*
4+
* This file is part of the Symfony package.
5+
*
6+
* (c) Fabien Potencier <fabien@symfony.com>
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*/
11+
12+
namespace Symfony\Component\OptionsResolver\Exception;
13+
14+
/**
15+
* Exception thrown when an undefined option is passed.
16+
*
17+
* You should remove the options in question from your code or define them
18+
* beforehand.
19+
*
20+
* @author Bernhard Schussek <bschussek@gmail.com>
21+
*/
22+
class UndefinedOptionsException extends InvalidArgumentException
23+
{
24+
}

0 commit comments

Comments
 (0)
0