feature #12891 [Form] Deprecated setDefaultOptions() in favor of conf…

…igureOptions() (peterrehm)

This PR was merged into the 2.7 branch.

Discussion
----------

[Form] Deprecated setDefaultOptions() in favor of configureOptions()

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | no
| BC breaks?    | no
| Deprecations? | yes
| Tests pass?   |
| Fixed tickets | #12782
| License       | MIT
| Doc PR        | symfony/symfony-docs#4786

This tries to provide a compatible API with the depreciation of the OptionResolverInterface. I would like to have this in 2.6.2 but I think that might not be possible? To me I think we should always provide an API where you do not need to use deprecated classes.

Also can you think of any way to trigger errors on the use of the deprecated setDefaultOptions() method? Since it is usually overwritten without calling the parent class this might be tricky. Maybe only in the resolver if we can check if actual options has been resolved in a call to setDefaultOptions.

Commits
-------

3d43cae Deprecated setDefaultOptions() in favor of configureOptions()

UPGRADE-2.7.md

@@ -1,7 +1,8 @@
 UPGRADE FROM 2.6 to 2.7
 =======================
 
-### Router
+Router
+------
 
  * Route conditions now support container parameters which
    can be injected into condition using `%parameter%` notation.
@@ -15,3 +16,46 @@ UPGRADE FROM 2.6 to 2.7
    but in 2.7 you would get an error if `bar` parameter
    doesn't exist or unexpected result otherwise.
 
+Form
+----
+
+ * In form types and extension overriding the "setDefaultOptions" of the
+   AbstractType or AbstractExtensionType has been deprecated in favor of
+   overriding the new "configureOptions" method.
+
+   The method "setDefaultOptions(OptionsResolverInterface $resolver)" will 
+   be renamed in Symfony 3.0 to "configureOptions(OptionsResolver $resolver)".
+
+   Before:
+
+   ```php
+        use Symfony\Component\OptionsResolver\OptionsResolverInterface;
+
+        class TaskType extends AbstractType
+        {
+            // ...
+            public function setDefaultOptions(OptionsResolverInterface $resolver)
+            {
+                $resolver->setDefaults(array(
+                    'data_class' => 'AppBundle\Entity\Task',
+                ));
+            }
+        }
+   ```
+
+   After:
+
+   ```php
+        use Symfony\Component\OptionsResolver\OptionsResolver;
+
+        class TaskType extends AbstractType
+        {
+            // ...
+            public function configureOptions(OptionsResolver $resolver)
+            {
+                $resolver->setDefaults(array(
+                    'data_class' => 'AppBundle\Entity\Task',
+                ));
+            }
+        }
+   ```

UPGRADE-3.0.md

@@ -106,6 +106,11 @@ UPGRADE FROM 2.x to 3.0
 
 ### Form
 
+ * The method `AbstractType::setDefaultOptions(OptionsResolverInterface $resolver)` and
+   `AbstractTypeExtension::setDefaultOptions(OptionsResolverInterface $resolver)` have been
+   renamed. You should use `AbstractType::configureOptions(OptionsResolver $resolver)` and
+   `AbstractTypeExtension::configureOptions(OptionsResolver $resolver)` instead.
+
  * The methods `Form::bind()` and `Form::isBound()` were removed. You should
    use `Form::submit()` and `Form::isSubmitted()` instead.
 

src/Symfony/Bridge/Doctrine/Form/Type/DoctrineType.php

@@ -21,7 +21,7 @@
 use Symfony\Bridge\Doctrine\Form\DataTransformer\CollectionToArrayTransformer;
 use Symfony\Component\Form\AbstractType;
 use Symfony\Component\OptionsResolver\Options;
-use Symfony\Component\OptionsResolver\OptionsResolverInterface;
+use Symfony\Component\OptionsResolver\OptionsResolver;
 use Symfony\Component\PropertyAccess\PropertyAccess;
 use Symfony\Component\PropertyAccess\PropertyAccessorInterface;
 
@@ -58,7 +58,7 @@ public function buildForm(FormBuilderInterface $builder, array $options)
         }
     }
 
-    public function setDefaultOptions(OptionsResolverInterface $resolver)
+    public function configureOptions(OptionsResolver $resolver)
     {
         $choiceListCache = & $this->choiceListCache;
         $registry = $this->registry;

src/Symfony/Bridge/Doctrine/composer.json

@@ -22,7 +22,7 @@
     "require-dev": {
         "symfony/stopwatch": "~2.2|~3.0.0",
         "symfony/dependency-injection": "~2.2|~3.0.0",
-        "symfony/form": "~2.3,>=2.3.8|~3.0.0",
+        "symfony/form": "~2.7|~3.0.0",
         "symfony/http-kernel": "~2.2|~3.0.0",
         "symfony/property-access": "~2.3|~3.0.0",
         "symfony/security": "~2.2|~3.0.0",

src/Symfony/Bridge/Propel1/Form/Type/ModelType.php

@@ -16,7 +16,7 @@
 use Symfony\Component\Form\AbstractType;
 use Symfony\Component\Form\FormBuilderInterface;
 use Symfony\Component\OptionsResolver\Options;
-use Symfony\Component\OptionsResolver\OptionsResolverInterface;
+use Symfony\Component\OptionsResolver\OptionsResolver;
 use Symfony\Component\PropertyAccess\PropertyAccess;
 use Symfony\Component\PropertyAccess\PropertyAccessorInterface;
 
@@ -78,7 +78,7 @@ public function buildForm(FormBuilderInterface $builder, array $options)
     /**
      * {@inheritdoc}
      */
-    public function setDefaultOptions(OptionsResolverInterface $resolver)
+    public function configureOptions(OptionsResolver $resolver)
     {
         $propertyAccessor = $this->propertyAccessor;
 

src/Symfony/Bridge/Propel1/Form/Type/TranslationCollectionType.php

@@ -14,7 +14,7 @@
 use Symfony\Component\Form\AbstractType;
 use Symfony\Component\OptionsResolver\Exception\MissingOptionsException;
 use Symfony\Component\Form\FormBuilderInterface;
-use Symfony\Component\OptionsResolver\OptionsResolverInterface;
+use Symfony\Component\OptionsResolver\OptionsResolver;
 use Symfony\Bridge\Propel1\Form\EventListener\TranslationCollectionFormListener;
 
 /**
@@ -59,7 +59,7 @@ public function getName()
     /**
      * {@inheritdoc}
      */
-    public function setDefaultOptions(OptionsResolverInterface $resolver)
+    public function configureOptions(OptionsResolver $resolver)
     {
         $resolver->setRequired(array(
             'languages',

src/Symfony/Bridge/Propel1/Form/Type/TranslationType.php

@@ -13,7 +13,7 @@
 
 use Symfony\Component\Form\AbstractType;
 use Symfony\Component\Form\FormBuilderInterface;
-use Symfony\Component\OptionsResolver\OptionsResolverInterface;
+use Symfony\Component\OptionsResolver\OptionsResolver;
 use Symfony\Bridge\Propel1\Form\EventListener\TranslationFormListener;
 
 /**
@@ -44,7 +44,7 @@ public function getName()
     /**
      * {@inheritdoc}
      */
-    public function setDefaultOptions(OptionsResolverInterface $resolver)
+    public function configureOptions(OptionsResolver $resolver)
     {
         $resolver->setRequired(array(
             'data_class',

src/Symfony/Bridge/Propel1/composer.json

@@ -19,7 +19,7 @@
         "php": ">=5.3.9",
         "symfony/http-foundation": "~2.0,>=2.0.5|~3.0.0",
         "symfony/http-kernel": "~2.0,>=2.0.5|~3.0.0",
-        "symfony/form": "~2.3,>=2.3.8|~3.0.0",
+        "symfony/form": "~2.7|~3.0.0",
         "symfony/property-access": "~2.3|~3.0.0",
         "propel/propel1": "~1.6,>=1.6.5"
     },

src/Symfony/Bundle/SecurityBundle/Tests/Functional/Bundle/CsrfFormLoginBundle/Form/UserLoginFormType.php

@@ -17,7 +17,7 @@
 use Symfony\Component\Form\FormEvents;
 use Symfony\Component\Form\FormEvent;
 use Symfony\Component\HttpFoundation\Request;
-use Symfony\Component\OptionsResolver\OptionsResolverInterface;
+use Symfony\Component\OptionsResolver\OptionsResolver;
 use Symfony\Component\Security\Core\Security;
 
 /**
@@ -77,7 +77,7 @@ public function buildForm(FormBuilderInterface $builder, array $options)
     /**
      * {@inheritdoc}
      */
-    public function setDefaultOptions(OptionsResolverInterface $resolver)
+    public function configureOptions(OptionsResolver $resolver)
     {
         /* Note: the form's intention must correspond to that for the form login
          * listener in order for the CSRF token to validate successfully.

src/Symfony/Component/Form/AbstractType.php

@@ -11,6 +11,7 @@
 
 namespace Symfony\Component\Form;
 
+use Symfony\Component\OptionsResolver\OptionsResolver;
 use Symfony\Component\OptionsResolver\OptionsResolverInterface;
 
 /**
@@ -43,6 +44,16 @@ public function finishView(FormView $view, FormInterface $form, array $options)
      * {@inheritdoc}
      */
     public function setDefaultOptions(OptionsResolverInterface $resolver)
+    {
+        $this->configureOptions($resolver);
+    }
+
+    /**
+     * Configures the options for this type.
+     *
+     * @param OptionsResolver $resolver The resolver for the options.
+     */
+    public function configureOptions(OptionsResolver $resolver)
     {
     }
 

src/Symfony/Component/Form/AbstractTypeExtension.php

@@ -11,6 +11,7 @@
 
 namespace Symfony\Component\Form;
 
+use Symfony\Component\OptionsResolver\OptionsResolver;
 use Symfony\Component\OptionsResolver\OptionsResolverInterface;
 
 /**
@@ -43,6 +44,16 @@ public function finishView(FormView $view, FormInterface $form, array $options)
      * {@inheritdoc}
      */
     public function setDefaultOptions(OptionsResolverInterface $resolver)
+    {
+        $this->configureOptions($resolver);
+    }
+
+    /**
+     * Configures the options for this type.
+     *
+     * @param OptionsResolver $resolver The resolver for the options.
+     */
+    public function configureOptions(OptionsResolver $resolver)
     {
     }
 }

src/Symfony/Component/Form/CHANGELOG.md

@@ -1,6 +1,12 @@
 CHANGELOG
 =========
 
+2.7.0
+-----
+
+ * deprecated the overwriting of AbstractType::setDefaultOptions() in favor of overwriting AbstractType::configureOptions().
+ * deprecated the overwriting of AbstractTypeExtension::setDefaultOptions() in favor of overwriting AbstractTypeExtension::configureOptions().
+
 2.6.2
 -----
 

src/Symfony/Component/Form/Extension/Core/Type/BaseType.php

@@ -15,7 +15,7 @@
 use Symfony\Component\Form\FormBuilderInterface;
 use Symfony\Component\Form\FormInterface;
 use Symfony\Component\Form\FormView;
-use Symfony\Component\OptionsResolver\OptionsResolverInterface;
+use Symfony\Component\OptionsResolver\OptionsResolver;
 
 /**
  * Encapsulates common logic of {@link FormType} and {@link ButtonType}.
@@ -111,7 +111,7 @@ public function buildView(FormView $view, FormInterface $form, array $options)
     /**
      * {@inheritdoc}
      */
-    public function setDefaultOptions(OptionsResolverInterface $resolver)
+    public function configureOptions(OptionsResolver $resolver)
     {
         $resolver->setDefaults(array(
             'block_name' => null,

src/Symfony/Component/Form/Extension/Core/Type/BirthdayType.php

@@ -12,14 +12,14 @@
 namespace Symfony\Component\Form\Extension\Core\Type;
 
 use Symfony\Component\Form\AbstractType;
-use Symfony\Component\OptionsResolver\OptionsResolverInterface;
+use Symfony\Component\OptionsResolver\OptionsResolver;
 
 class BirthdayType extends AbstractType
 {
     /**
      * {@inheritdoc}
      */
-    public function setDefaultOptions(OptionsResolverInterface $resolver)
+    public function configureOptions(OptionsResolver $resolver)
     {
         $resolver->setDefaults(array(
             'years' => range(date('Y') - 120, date('Y')),

src/Symfony/Component/Form/Extension/Core/Type/ButtonType.php

@@ -12,7 +12,7 @@
 namespace Symfony\Component\Form\Extension\Core\Type;
 
 use Symfony\Component\Form\ButtonTypeInterface;
-use Symfony\Component\OptionsResolver\OptionsResolverInterface;
+use Symfony\Component\OptionsResolver\OptionsResolver;
 
 /**
  * A form button.
@@ -39,9 +39,9 @@ public function getName()
     /**
      * {@inheritdoc}
      */
-    public function setDefaultOptions(OptionsResolverInterface $resolver)
+    public function configureOptions(OptionsResolver $resolver)
     {
-        parent::setDefaultOptions($resolver);
+        parent::configureOptions($resolver);
 
         $resolver->setDefaults(array(
             'auto_initialize' => false,

src/Symfony/Component/Form/Extension/Core/Type/CheckboxType.php

@@ -16,7 +16,7 @@
 use Symfony\Component\Form\FormInterface;
 use Symfony\Component\Form\Extension\Core\DataTransformer\BooleanToStringTransformer;
 use Symfony\Component\Form\FormView;
-use Symfony\Component\OptionsResolver\OptionsResolverInterface;
+use Symfony\Component\OptionsResolver\OptionsResolver;
 
 class CheckboxType extends AbstractType
 {
@@ -49,7 +49,7 @@ public function buildView(FormView $view, FormInterface $form, array $options)
     /**
      * {@inheritdoc}
      */
-    public function setDefaultOptions(OptionsResolverInterface $resolver)
+    public function configureOptions(OptionsResolver $resolver)
     {
         $emptyData = function (FormInterface $form, $viewData) {
             return $viewData;

src/Symfony/Component/Form/Extension/Core/Type/ChoiceType.php

@@ -26,7 +26,7 @@
 use Symfony\Component\Form\Extension\Core\DataTransformer\ChoicesToValuesTransformer;
 use Symfony\Component\Form\Extension\Core\DataTransformer\ChoicesToBooleanArrayTransformer;
 use Symfony\Component\OptionsResolver\Options;
-use Symfony\Component\OptionsResolver\OptionsResolverInterface;
+use Symfony\Component\OptionsResolver\OptionsResolver;
 
 class ChoiceType extends AbstractType
 {
@@ -161,7 +161,7 @@ public function finishView(FormView $view, FormInterface $form, array $options)
     /**
      * {@inheritdoc}
      */
-    public function setDefaultOptions(OptionsResolverInterface $resolver)
+    public function configureOptions(OptionsResolver $resolver)
     {
         $choiceListCache = & $this->choiceListCache;
 

src/Symfony/Component/Form/Extension/Core/Type/CollectionType.php

@@ -17,7 +17,7 @@
 use Symfony\Component\Form\FormInterface;
 use Symfony\Component\Form\Extension\Core\EventListener\ResizeFormListener;
 use Symfony\Component\OptionsResolver\Options;
-use Symfony\Component\OptionsResolver\OptionsResolverInterface;
+use Symfony\Component\OptionsResolver\OptionsResolver;
 
 class CollectionType extends AbstractType
 {
@@ -72,7 +72,7 @@ public function finishView(FormView $view, FormInterface $form, array $options)
     /**
      * {@inheritdoc}
      */
-    public function setDefaultOptions(OptionsResolverInterface $resolver)
+    public function configureOptions(OptionsResolver $resolver)
     {
         $optionsNormalizer = function (Options $options, $value) {
             $value['block_name'] = 'entry';

src/Symfony/Component/Form/Extension/Core/Type/CountryType.php

@@ -13,14 +13,14 @@
 
 use Symfony\Component\Form\AbstractType;
 use Symfony\Component\Intl\Intl;
-use Symfony\Component\OptionsResolver\OptionsResolverInterface;
+use Symfony\Component\OptionsResolver\OptionsResolver;
 
 class CountryType extends AbstractType
 {
     /**
      * {@inheritdoc}
      */
-    public function setDefaultOptions(OptionsResolverInterface $resolver)
+    public function configureOptions(OptionsResolver $resolver)
     {
         $resolver->setDefaults(array(
             'choices' => Intl::getRegionBundle()->getCountryNames(),

src/Symfony/Component/Form/Extension/Core/Type/CurrencyType.php

@@ -13,14 +13,14 @@
 
 use Symfony\Component\Form\AbstractType;
 use Symfony\Component\Intl\Intl;
-use Symfony\Component\OptionsResolver\OptionsResolverInterface;
+use Symfony\Component\OptionsResolver\OptionsResolver;
 
 class CurrencyType extends AbstractType
 {
     /**
      * {@inheritdoc}
      */
-    public function setDefaultOptions(OptionsResolverInterface $resolver)
+    public function configureOptions(OptionsResolver $resolver)
     {
         $resolver->setDefaults(array(
             'choices' => Intl::getCurrencyBundle()->getCurrencyNames(),