symfony · webmozart · Oct 22, 2014 · Oct 6, 2014
diff --git a/UPGRADE-2.6.md b/UPGRADE-2.6.md
@@ -128,3 +128,184 @@ HttpFoundation
      - You would need to migrate the table manually if you want to keep session information of your users.
      - You could use `PdoSessionHandler::createTable` to initialize a correctly defined table depending on
        the used database vendor.
+
+OptionsResolver
+---------------
+
+ * The "array" type hint was removed from the `OptionsResolverInterface` methods
+   `setRequired()`, `setAllowedValues()`, `addAllowedValues()`, 
+   `setAllowedTypes()` and `addAllowedTypes()`. You must remove the type hint
+   from your implementations.
+
+ * The interface `OptionsResolverInterface` was deprecated, since
+   `OptionsResolver` instances are not supposed to be shared between classes.
+   You should type hint against `OptionsResolver` instead.
+
+   Before:
+
+   ```php
+   protected function configureOptions(OptionsResolverInterface $resolver)
+   {
+       // ...
+   }
+   ```
+
+   After:
+
+   ```php
+   protected function configureOptions(OptionsResolver $resolver)
+   {
+       // ...
+   }
+   ```
+
+ * `OptionsResolver::isRequired()` now returns `true` if a required option has
+   a default value set. The new method `isMissing()` exhibits the old
+   functionality of `isRequired()`.
+
+   Before:
+
+   ```php
+   $resolver->setRequired(array('port'));
+
+   $resolver->isRequired('port');
+   // => true
+
+   $resolver->setDefaults(array('port' => 25));
+
+   $resolver->isRequired('port');
+   // => false
+   ```
+
+   After:
+
+   ```php
+   $resolver->setRequired(array('port'));
+
+   $resolver->isRequired('port');
+   // => true
+   $resolver->isMissing('port');
+   // => true
+
+   $resolver->setDefaults(array('port' => 25));
+
+   $resolver->isRequired('port');
+   // => true
+   $resolver->isMissing('port');
+   // => false
+   ```
+
+ * `OptionsResolver::replaceDefaults()` was deprecated. Use `clear()` and
+   `setDefaults()` instead.
+
+   Before:
+
+   ```php
+   $resolver->replaceDefaults(array(
+       'port' => 25,
+   ));
+   ```
+
+   After:
+
+   ```php
+   $resolver->clear();
+   $resolver->setDefaults(array(
+       'port' => 25,
+   ));
+   ```
+
+ * `OptionsResolver::setOptional()` was deprecated. Use `setDefined()` instead.
+
+   Before:
+
+   ```php
+   $resolver->setOptional(array('port'));
+   ```
+
+   After:
+
+   ```php
+   $resolver->setDefined('port');
+   ```
+
+ * `OptionsResolver::isKnown()` was deprecated. Use `isDefined()` instead.
+
+   Before:
+
+   ```php
+   if ($resolver->isKnown('port')) {
+       // ...
+   }
+   ```
+
+   After:
+
+   ```php
+   if ($resolver->isDefined('port')) {
+       // ...
+   }
+   ```
+
+ * The methods `setAllowedValues()`, `addAllowedValues()`, `setAllowedTypes()`
+   and `addAllowedTypes()` were changed to modify one option at a time instead
+   of batch processing options. The old API exists for backwards compatibility,
+   but will be removed in Symfony 3.0.
+
+   Before:
+
+   ```php
+   $resolver->setAllowedValues(array(
+       'method' => array('POST', 'GET'),
+   ));
+   ```
+
+   After:
+
+   ```php
+   $resolver->setAllowedValues('method', array('POST', 'GET'));
+   ```
+
+ * The class `Options` was merged into `OptionsResolver`. If you instantiated
+   this class manually, you should instantiate `OptionsResolver` now.
+   `Options` is now a marker interface implemented by `OptionsResolver`.
+
+   Before:
+
+   ```php
+   $options = new Options();
+   ```
+
+   After:
+
+   ```php
+   $resolver = new OptionsResolver();
+   ```
+
+ * Normalizers for defined but unset options are not executed anymore. If you 
+   want to have them executed, you should define a default value.
+
+   Before:
+
+   ```php
+   $resolver->setOptional(array('port'));
+   $resolver->setNormalizers(array(
+       'port' => function ($options, $value) {
+           // return normalized value
+       }
+   ));
+
+   $options = $resolver->resolve($options);
+   ```
+
+   After:
+
+   ```php
+   $resolver->setDefault('port', null);
+   $resolver->setNormalizer('port', function ($options, $value) {
+       // return normalized value
+   });
+
+   $options = $resolver->resolve($options);
+   ```
+
diff --git a/src/Symfony/Component/OptionsResolver/CHANGELOG.md b/src/Symfony/Component/OptionsResolver/CHANGELOG.md
@@ -0,0 +1,44 @@
+CHANGELOG
+=========
+
+2.6.0
+-----
+
+ * deprecated OptionsResolverInterface
+ * [BC BREAK] removed "array" type hint from OptionsResolverInterface methods
+   setRequired(), setAllowedValues(), addAllowedValues(), setAllowedTypes() and
+   addAllowedTypes()
+ * added OptionsResolver::setDefault()
+ * added OptionsResolver::hasDefault()
+ * added OptionsResolver::setNormalizer()
+ * added OptionsResolver::isRequired()
+ * added OptionsResolver::getRequiredOptions()
+ * added OptionsResolver::isMissing()
+ * added OptionsResolver::getMissingOptions()
+ * added OptionsResolver::setDefined()
+ * added OptionsResolver::isDefined()
+ * added OptionsResolver::getDefinedOptions()
+ * added OptionsResolver::remove()
+ * added OptionsResolver::clear()
+ * deprecated OptionsResolver::replaceDefaults()
+ * deprecated OptionsResolver::setOptional() in favor of setDefined()
+ * deprecated OptionsResolver::isKnown() in favor of isDefined()
+ * [BC BREAK] OptionsResolver::isRequired() returns true now if a required
+   option has a default value set
+ * [BC BREAK] merged Options into OptionsResolver and turned Options into an 
+   interface
+ * deprecated Options::overload() (now in OptionsResolver)
+ * deprecated Options::set() (now in OptionsResolver)
+ * deprecated Options::get() (now in OptionsResolver)
+ * deprecated Options::has() (now in OptionsResolver)
+ * deprecated Options::replace() (now in OptionsResolver)
+ * [BC BREAK] Options::get() (now in OptionsResolver) can only be used within
+   lazy option/normalizer closures now
+ * [BC BREAK] removed Traversable interface from Options since using within
+   lazy option/normalizer closures resulted in exceptions
+ * [BC BREAK] removed Options::all() since using within lazy option/normalizer 
+   closures resulted in exceptions
+ * [BC BREAK] OptionDefinitionException now extends LogicException instead of
+   RuntimeException
+ * [BC BREAK] normalizers are not executed anymore for unset options
+ * normalizers are executed after validating the options now
diff --git a/src/Symfony/Component/OptionsResolver/Exception/AccessException.php b/src/Symfony/Component/OptionsResolver/Exception/AccessException.php
@@ -0,0 +1,22 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\OptionsResolver\Exception;
+
+/**
+ * Thrown when trying to read an option outside of or write it inside of
+ * {@link Options::resolve()}.
+ *
+ * @author Bernhard Schussek <bschussek@gmail.com>
+ */
+class AccessException extends \LogicException implements ExceptionInterface
+{
+}
diff --git a/src/Symfony/Component/OptionsResolver/Exception/InvalidArgumentException.php b/src/Symfony/Component/OptionsResolver/Exception/InvalidArgumentException.php
@@ -0,0 +1,21 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\OptionsResolver\Exception;
+
+/**
+ * Thrown when an argument is invalid.
+ *
+ * @author Bernhard Schussek <bschussek@gmail.com>
+ */
+class InvalidArgumentException extends \InvalidArgumentException implements ExceptionInterface
+{
+}
diff --git a/src/Symfony/Component/OptionsResolver/Exception/InvalidOptionsException.php b/src/Symfony/Component/OptionsResolver/Exception/InvalidOptionsException.php
@@ -12,10 +12,12 @@
 namespace Symfony\Component\OptionsResolver\Exception;
 
 /**
- * Exception thrown when an invalid option is passed.
+ * Thrown when the value of an option does not match its validation rules.
+ *
+ * You should make sure a valid value is passed to the option.
  *
  * @author Bernhard Schussek <bschussek@gmail.com>
  */
-class InvalidOptionsException extends \InvalidArgumentException implements ExceptionInterface
+class InvalidOptionsException extends InvalidArgumentException
 {
 }
diff --git a/src/Symfony/Component/OptionsResolver/Exception/MissingOptionsException.php b/src/Symfony/Component/OptionsResolver/Exception/MissingOptionsException.php
@@ -14,8 +14,10 @@
 /**
  * Exception thrown when a required option is missing.
  *
+ * Add the option to the passed options array.
+ *
  * @author Bernhard Schussek <bschussek@gmail.com>
  */
-class MissingOptionsException extends \InvalidArgumentException implements ExceptionInterface
+class MissingOptionsException extends InvalidArgumentException
 {
 }
diff --git a/src/Symfony/Component/OptionsResolver/Exception/OptionDefinitionException.php b/src/Symfony/Component/OptionsResolver/Exception/OptionDefinitionException.php
@@ -12,10 +12,10 @@
 namespace Symfony\Component\OptionsResolver\Exception;
 
 /**
- * Thrown when an option definition is invalid.
+ * Thrown when two lazy options have a cyclic dependency.
  *
  * @author Bernhard Schussek <bschussek@gmail.com>
  */
-class OptionDefinitionException extends \RuntimeException implements ExceptionInterface
+class OptionDefinitionException extends \LogicException implements ExceptionInterface
 {
 }
diff --git a/src/Symfony/Component/OptionsResolver/Exception/UndefinedOptionsException.php b/src/Symfony/Component/OptionsResolver/Exception/UndefinedOptionsException.php
@@ -0,0 +1,24 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\OptionsResolver\Exception;
+
+/**
+ * Exception thrown when an undefined option is passed.
+ *
+ * You should remove the options in question from your code or define them
+ * beforehand.
+ *
+ * @author Bernhard Schussek <bschussek@gmail.com>
+ */
+class UndefinedOptionsException extends InvalidArgumentException
+{
+}