[Form] form add extra data

forms.rst

@@ -947,6 +947,72 @@ These "unmapped fields" can be set and accessed in a controller with::
 Additionally, if there are any fields on the form that aren't included in
 the submitted data, those fields will be explicitly set to ``null``.
 
+Extra fields
+~~~~~~~~~~~~
+
+All form fields are considered properties of the object but you can inject
+fields directly into your view without specifying them in the form definition.
+They can be retrieved via the ``getExtraData`` :class:`Symfony\\Component\\Form\\FormTypeInterface`.
+
+This is a creation user form::
+
+    // ...
+    use App\User;
+    use Symfony\Component\Form\Extension\Core\Type\CheckboxType;
+    use Symfony\Component\Form\Extension\Core\Type\SubmitType;
+    use Symfony\Component\Form\FormBuilderInterface;
+
+    class UserCreateType extends AbstractType
+    {
+        public function buildForm(FormBuilderInterface $builder, array $options): void
+        {
+            $builder
+                ->add('username', TextType::class)
+                ->add('email', EmailType::class)
+            ;
+        }
+
+        public function configureOptions(OptionsResolver $resolver)
+        {
+            $resolver->setDefaults([
+                'data_class' => User::class,
+            ]);
+        }
+    }
+
+The extra fields can be injected like this:
+
+.. code-block:: html+twig
+
+    {# templates/user/create.html.twig #}
+    {{ form_start(form) }}
+        {{ form_row(form.username) }}
+        {{ form_row(form.email) }}
+
+        {# Hidden field to send additional referral code #}
+        <input type="hidden" name="user_create[referralCode]" value="{{ referralCode }}"/>
+
+        <button type="submit">Submit</button>
+    {{ form_end(form) }}
+
+Here, the referral code is an extra field injected at view level.
+
+The field name is composed of form ``user_create`` and the field name ``referralCode``.
+It's automatically generated from the form class name. You can :ref:`override it <changing-the-form-name>`
+
+Or you can use
+
+.. code-block:: twig
+
+    {{ form.vars.full_name ~ '[referralCode]' }}
+
+to render the form name dynamically
+
+You can get the referral code via ``getExtraData``::
+
+    $extraData = $form->getExtraData();
+    $referralCode = $extraData['referralCode'] ?? null;
+
 Learn more
 ----------