feature #35400 [RFC][DX][OptionsResolver] Allow setting info message per option (yceruto)

This PR was merged into the 5.1-dev branch.

Discussion
----------

[RFC][DX][OptionsResolver] Allow setting info message per option

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Tickets       | -
| License       | MIT
| Doc PR        | TODO

This is a DX proposal that will help in debugging/errors to better understand the meaning of one defined option.

This is how you'd use it:
```php
$resolver = new OptionsResolver();
$resolver->setDefined('date');
$resolver->setAllowedTypes('date', \DateTime::class);
$resolver->setInfo('date', 'A future date'); // <-- NEW
// ...
```
This information may be useful for those options where their name cannot be intuitive enough, or their purpose is too complex. Here is an example (based on the example above):
```php
// ...
$resolver->setAllowedValues('date', static function ($value): bool {
    return $value >= new \DateTime('now');
});
```
So, if you introduce a date value that does not match the criteria, you will get this error message:

**Before:**
```
The option "date" with value DateTime is invalid.
```
Note that the allowed value is not printable in this case, hence the error message cannot be clear at all.

**After:**
```
The option "date" with value DateTime is invalid. Info: A future date.
```
Although a more accurate error message can be triggered within the `\Closure` if desired.

Also you'll see this info message on `debug:form` command (see tests), then you have in advance the informative description of any option.

What do you think?

Commits
-------

0477a06d8a Allow setting one info message per option

Author: fabpot

Console/Descriptor/Descriptor.php

@@ -108,7 +108,15 @@ protected function collectOptions(ResolvedFormTypeInterface $type)
 
     protected function getOptionDefinition(OptionsResolver $optionsResolver, string $option)
     {
-        $definition = [
+        $definition = [];
+
+        if ($info = $optionsResolver->getInfo($option)) {
+            $definition = [
+                'info' => $info,
+            ];
+        }
+
+        $definition += [
             'required' => $optionsResolver->isRequired($option),
             'deprecated' => $optionsResolver->isDeprecated($option),
         ];

Console/Descriptor/JsonDescriptor.php

@@ -73,6 +73,7 @@ protected function describeOption(OptionsResolver $optionsResolver, array $optio
             }
         }
         $map += [
+            'info' => 'info',
             'required' => 'required',
             'default' => 'default',
             'allowed_types' => 'allowedTypes',

Console/Descriptor/TextDescriptor.php

@@ -114,6 +114,7 @@ protected function describeOption(OptionsResolver $optionsResolver, array $optio
             ];
         }
         $map += [
+            'Info' => 'info',
             'Required' => 'required',
             'Default' => 'default',
             'Allowed types' => 'allowedTypes',

Tests/Command/DebugCommandTest.php

@@ -151,6 +151,8 @@ public function testDebugCustomFormTypeOption()
 Symfony\Component\Form\Tests\Command\FooType (foo)
 ==================================================
 
+ ---------------- -----------%s
+  Info             "Info"    %s
  ---------------- -----------%s
   Required         true      %s
  ---------------- -----------%s
@@ -209,5 +211,6 @@ public function configureOptions(OptionsResolver $resolver)
         $resolver->setNormalizer('foo', function (Options $options, $value) {
             return (string) $value;
         });
+        $resolver->setInfo('foo', 'Info');
     }
 }

Tests/Fixtures/Descriptor/default_option_with_normalizer.txt

@@ -2,6 +2,8 @@
 Symfony\Component\Form\Extension\Core\Type\ChoiceType (choice_translation_domain)
 =================================================================================
 
+ ---------------- -----------%s
+  Info             -         %s
  ---------------- -----------%s
   Required         false     %s
  ---------------- -----------%s

Tests/Fixtures/Descriptor/deprecated_option.txt

@@ -5,6 +5,8 @@ Symfony\Component\Form\Tests\Console\Descriptor\FooType (bar)
   Deprecated            true                               
  --------------------- ----------------------------------- 
   Deprecation message   "The option "bar" is deprecated."  
+ --------------------- ----------------------------------- 
+  Info                  -                                  
  --------------------- ----------------------------------- 
   Required              false                              
  --------------------- ----------------------------------- 
@@ -15,4 +17,4 @@ Symfony\Component\Form\Tests\Console\Descriptor\FooType (bar)
   Allowed values        -                                  
  --------------------- ----------------------------------- 
   Normalizers           -                                  
- --------------------- -----------------------------------
+ --------------------- -----------------------------------

Tests/Fixtures/Descriptor/overridden_option_with_default_closures.txt

@@ -2,6 +2,8 @@ Symfony\Component\Form\Tests\Console\Descriptor\FooType (empty_data)
 ====================================================================
 
  ---------------- ----------------------%s 
+  Info             -                    %s 
+ ---------------- ----------------------%s
   Required         false                %s 
  ---------------- ----------------------%s 
   Default          Value: null          %s 

Tests/Fixtures/Descriptor/required_option_with_allowed_values.txt

@@ -2,6 +2,8 @@
 Symfony\Component\Form\Tests\Console\Descriptor\FooType (foo)
 =============================================================
 
+ ---------------- -----------%s
+  Info             -         %s
  ---------------- -----------%s
   Required         true      %s
  ---------------- -----------%s

composer.json

@@ -20,7 +20,7 @@
         "symfony/deprecation-contracts": "^2.1",
         "symfony/event-dispatcher": "^4.4|^5.0",
         "symfony/intl": "^4.4|^5.0",
-        "symfony/options-resolver": "^5.0",
+        "symfony/options-resolver": "^5.1",
         "symfony/polyfill-ctype": "~1.8",
         "symfony/polyfill-mbstring": "~1.0",
         "symfony/property-access": "^5.0",