From 16ffcdae52493d4f23c1841e56a32aad81531f7b Mon Sep 17 00:00:00 2001
From: Javier Eguiluz <javier.eguiluz@gmail.com>
Date: Thu, 18 Nov 2021 16:29:39 +0100
Subject: [PATCH] [Form] Add the docs for EnumType

---
 reference/forms/types.rst         |   1 +
 reference/forms/types/enum.rst    | 119 ++++++++++++++++++++++++++++++
 reference/forms/types/map.rst.inc |   1 +
 3 files changed, 121 insertions(+)
 create mode 100644 reference/forms/types/enum.rst

diff --git a/reference/forms/types.rst b/reference/forms/types.rst
index 61ff1b5bf86..eaa0344f141 100644
--- a/reference/forms/types.rst
+++ b/reference/forms/types.rst
@@ -23,6 +23,7 @@ Form Types Reference
    types/color
 
    types/choice
+   types/enum
    types/entity
    types/country
    types/language
diff --git a/reference/forms/types/enum.rst b/reference/forms/types/enum.rst
new file mode 100644
index 00000000000..e9842516acc
--- /dev/null
+++ b/reference/forms/types/enum.rst
@@ -0,0 +1,119 @@
+.. index::
+   single: Forms; Fields; EnumType
+
+EnumType Field
+==============
+
+.. versionadded:: 5.4
+
+   The ``EnumType`` form field was introduced in Symfony 5.4.
+
+A multi-purpose field used to allow the user to "choose" one or more options
+defined in a `PHP enumeration`_. It extends the :doc:`ChoiceType </refernce/forms/types/enum>`
+field and defines the same options.
+
++---------------------------+----------------------------------------------------------------------+
+| Rendered as               | can be various tags (see below)                                      |
++---------------------------+----------------------------------------------------------------------+
+| Default invalid message   | The selected choice is invalid.                                      |
++---------------------------+----------------------------------------------------------------------+
+| Legacy invalid message    | The value {{ value }} is not valid.                                  |
++---------------------------+----------------------------------------------------------------------+
+| Parent type               | :doc:`ChoiceType </reference/forms/types/choice>`                    |
++---------------------------+----------------------------------------------------------------------+
+| Class                     | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\EnumType`   |
++---------------------------+----------------------------------------------------------------------+
+
+.. include:: /reference/forms/types/options/_debug_form.rst.inc
+
+Example Usage
+-------------
+
+Before using this field, you'll need to have some PHP enumeration (or "enum" for
+short) defined somewhere in your application. This enum has to be of type
+"backed enum", where each keyword defines a scalar value such a string::
+
+    // src/Config/TextAlign.php
+    namespace App\Config;
+
+    enum TextAlign
+    {
+        case Left = 'Left/Start aligned';
+        case Center = 'Center/Middle aligned';
+        case Right = 'Right/End aligned';
+    }
+
+Instead of using the values of the enumeration in a ``choices`` option, the
+``EnumType`` only requires to define the ``class`` option pointing to the enum::
+
+    use App\Config\TextAlign;
+    use Symfony\Component\Form\Extension\Core\Type\EnumType;
+    // ...
+
+    $builder->add('alignment', EnumType::class, ['class' => TextAlign::class]);
+
+This will display a ``<select>`` tag with the three possible values defined in
+the ``TextAlign`` enum. Use the ``expanded`` and ``multiple`` options to display
+these values as ``<input type="checkbox">`` and ``<input type="radio">``.
+
+Field Options
+-------------
+
+class
+~~~~~
+
+**type**: ``string`` **default**: (it has no default)
+
+The fully-qualified class name (FQCN) of the PHP enum used to get the values
+displayed by this form field.
+
+Inherited Options
+-----------------
+
+These options inherit from the :doc:`ChoiceType </reference/forms/types/choice>`:
+
+.. include:: /reference/forms/types/options/error_bubbling.rst.inc
+
+.. include:: /reference/forms/types/options/error_mapping.rst.inc
+
+.. include:: /reference/forms/types/options/expanded.rst.inc
+
+.. include:: /reference/forms/types/options/multiple.rst.inc
+
+.. include:: /reference/forms/types/options/placeholder.rst.inc
+
+.. include:: /reference/forms/types/options/preferred_choices.rst.inc
+
+.. include:: /reference/forms/types/options/choice_type_trim.rst.inc
+
+These options inherit from the :doc:`FormType </reference/forms/types/form>`:
+
+.. include:: /reference/forms/types/options/attr.rst.inc
+
+.. include:: /reference/forms/types/options/data.rst.inc
+
+.. include:: /reference/forms/types/options/disabled.rst.inc
+
+.. include:: /reference/forms/types/options/empty_data_declaration.rst.inc
+
+.. include:: /reference/forms/types/options/empty_data_description.rst.inc
+
+.. include:: /reference/forms/types/options/help.rst.inc
+
+.. include:: /reference/forms/types/options/help_attr.rst.inc
+
+.. include:: /reference/forms/types/options/help_html.rst.inc
+
+.. include:: /reference/forms/types/options/label.rst.inc
+
+.. include:: /reference/forms/types/options/label_attr.rst.inc
+
+.. include:: /reference/forms/types/options/label_format.rst.inc
+
+.. include:: /reference/forms/types/options/mapped.rst.inc
+
+.. include:: /reference/forms/types/options/required.rst.inc
+
+.. include:: /reference/forms/types/options/row_attr.rst.inc
+
+.. _`PHP enumeration`: https://wiki.php.net/rfc/enumerations
diff --git a/reference/forms/types/map.rst.inc b/reference/forms/types/map.rst.inc
index 8171c836a4d..4d1ed612c67 100644
--- a/reference/forms/types/map.rst.inc
+++ b/reference/forms/types/map.rst.inc
@@ -19,6 +19,7 @@ Choice Fields
 ~~~~~~~~~~~~~
 
 * :doc:`ChoiceType </reference/forms/types/choice>`
+* :doc:`EnumType </reference/forms/types/enum>`
 * :doc:`EntityType </reference/forms/types/entity>`
 * :doc:`CountryType </reference/forms/types/country>`
 * :doc:`LanguageType </reference/forms/types/language>`