[Form] Add duplicate_preferred_choices option to ChoiceType

reference/forms/types/choice.rst

@@ -188,6 +188,8 @@ correct types will be assigned to the model.
 
 .. include:: /reference/forms/types/options/choice_value.rst.inc
 
+.. include:: /reference/forms/types/options/duplicate_preferred_choices.rst.inc
+
 .. include:: /reference/forms/types/options/expanded.rst.inc
 
 .. include:: /reference/forms/types/options/group_by.rst.inc

reference/forms/types/country.rst

@@ -68,6 +68,8 @@ Inherited Options
 
 These options inherit from the :doc:`ChoiceType </reference/forms/types/choice>`:
 
+.. include:: /reference/forms/types/options/duplicate_preferred_choices.rst.inc
+
 .. include:: /reference/forms/types/options/error_bubbling.rst.inc
 
 .. include:: /reference/forms/types/options/error_mapping.rst.inc

reference/forms/types/currency.rst

@@ -51,6 +51,8 @@ Inherited Options
 
 These options inherit from the :doc:`ChoiceType </reference/forms/types/choice>`:
 
+.. include:: /reference/forms/types/options/duplicate_preferred_choices.rst.inc
+
 .. include:: /reference/forms/types/options/error_bubbling.rst.inc
 
 .. include:: /reference/forms/types/options/expanded.rst.inc

reference/forms/types/enum.rst

@@ -159,6 +159,8 @@ This callback will group choices in 3 categories: ``Upper``, ``Lower`` and ``Oth
 
 If you return ``null``, the option won't be grouped.
 
+.. include:: /reference/forms/types/options/duplicate_preferred_choices.rst.inc
+
 .. include:: /reference/forms/types/options/multiple.rst.inc
 
 .. include:: /reference/forms/types/options/placeholder.rst.inc

reference/forms/types/language.rst

@@ -85,6 +85,8 @@ Inherited Options
 
 These options inherit from the :doc:`ChoiceType </reference/forms/types/choice>`:
 
+.. include:: /reference/forms/types/options/duplicate_preferred_choices.rst.inc
+
 .. include:: /reference/forms/types/options/error_bubbling.rst.inc
 
 .. include:: /reference/forms/types/options/error_mapping.rst.inc

reference/forms/types/locale.rst

@@ -62,6 +62,8 @@ Inherited Options
 
 These options inherit from the :doc:`ChoiceType </reference/forms/types/choice>`:
 
+.. include:: /reference/forms/types/options/duplicate_preferred_choices.rst.inc
+
 .. include:: /reference/forms/types/options/error_bubbling.rst.inc
 
 .. include:: /reference/forms/types/options/error_mapping.rst.inc

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

@@ -0,0 +1,27 @@
+``duplicate_preferred_choices``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**type**: ``boolean`` **default**: ``true``
+
+When using the ``preferred_choices`` option, the selected choices are displayed
+twice by default: at the top of your list and in the complete list. You can
+change this behavior: when setting this option to ``false``, preferred choices
+will only be displayed at the top of the list.
+
+    use Symfony\Component\Form\Extension\Core\Type\ChoiceType;
+    // ...
+
+    $builder->add('language', ChoiceType::class, [
+        'choices' => [
+            'English' => 'en',
+            'Spanish' => 'es',
+            'Bork' => 'muppets',
+            'Pirate' => 'arr',
+        ],
+        'preferred_choices' => ['muppets', 'arr'],
+        'duplicate_preferred_choices' => false,
+    ]);
+
+.. versionadded:: 6.4
+
+    The ``duplicate_preferred_choices`` option was introduced in Symfony 6.4.

reference/forms/types/timezone.rst

@@ -83,6 +83,8 @@ Inherited Options
 
 These options inherit from the :doc:`ChoiceType </reference/forms/types/choice>`:
 
+.. include:: /reference/forms/types/options/duplicate_preferred_choices.rst.inc
+
 .. include:: /reference/forms/types/options/expanded.rst.inc
 
 .. include:: /reference/forms/types/options/multiple.rst.inc