feature #27667 [Form][OptionsResolver] Show deprecated options definition on debug:form command (yceruto)

This PR was merged into the 4.2-dev branch.

Discussion
----------

[Form][OptionsResolver] Show deprecated options definition on debug:form command

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | -
| License       | MIT
| Doc PR        | -

Next move after symfony/symfony#27277.

It will look like this:

Use `--show-deprecated` option to show form types with deprecated options (example):
![debug_types_with_deprecated_options](https://user-images.githubusercontent.com/2028198/41823977-970c7c98-77d6-11e8-9e97-30dcedc316ac.png)

Use `--show-deprecated` option to show deprecated options of the given form type (example):
![debug_deprecated_options_from_type](https://user-images.githubusercontent.com/2028198/41823980-a4d6bd8e-77d6-11e8-95ed-39926ffd6235.png)

Deprecated option (example):
![debug_deprecated_option_text](https://user-images.githubusercontent.com/2028198/41689091-04e6b7dc-74bd-11e8-87d0-90729eac4bb3.png)

![debug_deprecated_option_json](https://user-images.githubusercontent.com/2028198/41689105-142b5c5c-74bd-11e8-9232-1f30237bcf69.png)

Commits
-------

87c209d741 Show deprecated options definition on debug:form command

Author: fabpot

Debug/OptionsResolverIntrospector.php

@@ -87,4 +87,14 @@ public function getNormalizer(string $option): \Closure
     {
         return \call_user_func($this->get, 'normalizers', $option, sprintf('No normalizer was set for the "%s" option.', $option));
     }
+
+    /**
+     * @return string|\Closure
+     *
+     * @throws NoConfigurationException on no configured deprecation
+     */
+    public function getDeprecationMessage(string $option)
+    {
+        return \call_user_func($this->get, 'deprecated', $option, sprintf('No deprecation was set for the "%s" option.', $option));
+    }
 }

Tests/Debug/OptionsResolverIntrospectorTest.php

@@ -200,4 +200,49 @@ public function testGetNormalizerThrowsOnNotDefinedOption()
         $debug = new OptionsResolverIntrospector($resolver);
         $this->assertSame('bar', $debug->getNormalizer('foo'));
     }
+
+    public function testGetDeprecationMessage()
+    {
+        $resolver = new OptionsResolver();
+        $resolver->setDefined('foo');
+        $resolver->setDeprecated('foo', 'The option "foo" is deprecated.');
+
+        $debug = new OptionsResolverIntrospector($resolver);
+        $this->assertSame('The option "foo" is deprecated.', $debug->getDeprecationMessage('foo'));
+    }
+
+    public function testGetClosureDeprecationMessage()
+    {
+        $resolver = new OptionsResolver();
+        $resolver->setDefined('foo');
+        $resolver->setDeprecated('foo', $closure = function ($value) {});
+
+        $debug = new OptionsResolverIntrospector($resolver);
+        $this->assertSame($closure, $debug->getDeprecationMessage('foo'));
+    }
+
+    /**
+     * @expectedException \Symfony\Component\OptionsResolver\Exception\NoConfigurationException
+     * @expectedExceptionMessage No deprecation was set for the "foo" option.
+     */
+    public function testGetDeprecationMessageThrowsOnNoConfiguredValue()
+    {
+        $resolver = new OptionsResolver();
+        $resolver->setDefined('foo');
+
+        $debug = new OptionsResolverIntrospector($resolver);
+        $this->assertSame('bar', $debug->getDeprecationMessage('foo'));
+    }
+
+    /**
+     * @expectedException \Symfony\Component\OptionsResolver\Exception\UndefinedOptionsException
+     * @expectedExceptionMessage The option "foo" does not exist.
+     */
+    public function testGetDeprecationMessageThrowsOnNotDefinedOption()
+    {
+        $resolver = new OptionsResolver();
+
+        $debug = new OptionsResolverIntrospector($resolver);
+        $this->assertSame('bar', $debug->getDeprecationMessage('foo'));
+    }
 }