[Form] minor fixes in ChoiceType options

Author: HeahDude

reference/forms/types/choice.rst

@@ -95,23 +95,31 @@ method::
             new Category('Cat3'),
             new Category('Cat4'),
         ],
-        'choice_label' => function(Category $category, $key, $value) {
-            return strtoupper($category->getName());
+        // a property path can by used to define the options below
+        'choice_value' => 'name',
+        // the empty value can be passed if there is a placeholder
+        'choice_label' => function(?Category $category) {
+            return $category ? strtoupper($category->getName()) : '';
         },
-        'choice_attr' => function(Category $category, $key, $value) {
-            return ['class' => 'category_'.strtolower($category->getName())];
+        'choice_attr' => function(?Category $category) {
+            return $category ? ['class' => 'category_'.strtolower($category->getName())] : [];
         },
-        'group_by' => function(Category $category, $key, $value) {
+        'group_by' => function() {
             // randomly assign things into 2 groups
             return rand(0, 1) == 1 ? 'Group A' : 'Group B';
         },
-        'preferred_choices' => function(Category $category, $key, $value) {
-            return $category->getName() == 'Cat2' || $category->getName() == 'Cat3';
+        // the empty value maybe passed if a placeholder is used
+        'preferred_choices' => function(?Category $category) {
+            if (null === $category) {
+                return false;
+            }
+
+            return in_array($category->getName(), ['Cat2', 'Cat3'], true);
         },
     ]);
 
-You can also customize the `choice_name`_ and `choice_value`_ of each choice if
-you need further HTML customization.
+You can also customize the `choice_name`_ of each choice. You can learn more
+about all of them in the sections below.
 
 .. _forms-reference-choice-tags:
 
@@ -151,7 +159,7 @@ by passing a multi-dimensional ``choices`` array::
 .. image:: /_images/reference/form/choice-example4.png
    :align: center
 
-To get fancier, use the `group_by`_ option.
+To get fancier, use the `group_by`_ option instead.
 
 Field Options
 -------------
@@ -169,7 +177,10 @@ is the item's label and the array value is the item's value::
     // ...
 
     $builder->add('inStock', ChoiceType::class, [
-        'choices' => ['In Stock' => true, 'Out of Stock' => false],
+        'choices' => [
+            'In Stock' => true,
+            'Out of Stock' => false,
+        ],
     ]);
 
 If there are choice values that are not scalar or the stringified

reference/forms/types/options/choice_attr.rst.inc

@@ -1,7 +1,7 @@
 ``choice_attr``
 ~~~~~~~~~~~~~~~
 
-**type**: ``array``, ``callable`` or ``string`` **default**: ``[]``
+**type**: ``array``, ``callable``, ``string`` or :class:`Symfony\\Component\\PropertyAccess\\PropertyPath` **default**: ``[]``
 
 Use this to add additional HTML attributes to each choice. This can be
 an associative array where the keys match the choice keys and the values

reference/forms/types/options/choice_label.rst.inc

@@ -1,9 +1,9 @@
 ``choice_label``
 ~~~~~~~~~~~~~~~~
 
-**type**: ``string``, ``callable`` or ``false`` **default**: ``null``
+**type**: ``string``, ``callable``, ``false`` or :class:`Symfony\\Component\\PropertyAccess\\PropertyPath` **default**: ``null``
 
-Normally, the array key of each item in the ``choices`` option is used as the
+By default, the array key of each item in the ``choices`` option is used as the
 text that's shown to the user. The ``choice_label`` option allows you to take
 more control::
 

reference/forms/types/options/choice_name.rst.inc

@@ -1,14 +1,15 @@
 ``choice_name``
 ~~~~~~~~~~~~~~~
 
-**type**: ``callable`` or ``string`` **default**: ``null``
+**type**: ``callable``, ``string`` or :class:`Symfony\\Component\\PropertyAccess\\PropertyPath` **default**: ``null``
 
 Controls the internal field name of the choice. You normally don't care about this,
 but in some advanced cases, you might. For example, this "name" becomes the index
-of the choice views in the template.
+of the choice views in the template and is used as part o the field name
+attribute.
 
 This can be a callable or a property path. See `choice_label`_ for similar usage.
-If ``null`` is used, an incrementing integer is used as the name.
+By default, the choice key or an incrementing integer may be used.
 
 .. caution::
 

reference/forms/types/options/choice_value.rst.inc

@@ -1,28 +1,20 @@
 ``choice_value``
 ~~~~~~~~~~~~~~~~
 
-**type**: ``callable`` or ``string`` **default**: ``null``
+**type**: ``callable``, ``string`` or :class:`Symfony\\Component\\PropertyAccess\\PropertyPath` **default**: ``null``
 
 Returns the string "value" for each choice, which must be unique across all choices.
 This is used in the ``value`` attribute in HTML and submitted in the POST/PUT requests.
 You don't normally need to worry about this, but it might be handy when processing
 an API request (since you can configure the value that will be sent in the API request).
 
-This can be a callable or a property path. If ``null`` is given, an incrementing
-integer is used as the value.
+This can be a callable or a property path. By default, the choices are used if they
+can be casted to strings. Otherwise an incrementing integer is used.
 
 If you pass a callable, it will receive one argument: the choice itself. When using
 the :doc:`/reference/forms/types/entity`, the argument will be the entity object
-for each choice or ``null`` in some cases, which you need to handle::
+for each choice or ``null`` in a placeholder is used, which you need to handle::
 
-    'choice_value' => function (MyOptionEntity $entity = null) {
+    'choice_value' => function (?MyOptionEntity $entity) {
         return $entity ? $entity->getId() : '';
     },
-
-.. caution::
-
-    In Symfony 2.7, there was a small backwards-compatibility break with how the
-    ``value`` attribute of options is generated. This is not a problem unless you
-    rely on the option values in JavaScript. See `issue #14825`_ for details.
-
-.. _`issue #14825`: https://github.com/symfony/symfony/pull/14825

reference/forms/types/options/group_by.rst.inc

@@ -1,7 +1,7 @@
 ``group_by``
 ~~~~~~~~~~~~
 
-**type**: ``string`` or ``callable`` **default**: ``null``
+**type**: ``string``, ``callable`` or :class:`Symfony\\Component\\PropertyAccess\\PropertyPath` **default**: ``null``
 
 You can group the ``<option>`` elements of a ``<select>`` into ``<optgroup>``
 by passing a multi-dimensional array to ``choices``. See the
@@ -25,9 +25,9 @@ Take the following example::
         'group_by' => function($choice, $key, $value) {
             if ($choice <= new \DateTime('+3 days')) {
                 return 'Soon';
-            } else {
-                return 'Later';
             }
+
+            return 'Later';
         },
     ]);
 

reference/forms/types/options/preferred_choices.rst.inc

@@ -1,11 +1,11 @@
 ``preferred_choices``
 ~~~~~~~~~~~~~~~~~~~~~
 
-**type**: ``array``, ``callable`` or ``string`` **default**: ``[]``
+**type**: ``array``, ``callable``, ``string`` or :class:`Symfony\\Component\\PropertyAccess\\PropertyPath` **default**: ``[]``
 
 This option allows you to move certain choices to the top of your list with a visual
 separator between them and the rest of the options. If you have a form of languages,
-you can list the most popular on top, like Bork Bork and Pirate::
+you can list the most popular on top, like Bork and Pirate::
 
     use Symfony\Component\Form\Extension\Core\Type\ChoiceType;
     // ...
@@ -14,7 +14,7 @@ you can list the most popular on top, like Bork Bork and Pirate::
         'choices' => [
             'English' => 'en',
             'Spanish' => 'es',
-            'Bork'   => 'muppets',
+            'Bork' => 'muppets',
             'Pirate' => 'arr',
         ],
         'preferred_choices' => ['muppets', 'arr'],