From 34ef0ffcef10323f5499e6a744540664b547cfd4 Mon Sep 17 00:00:00 2001 From: Jules Pietri Date: Sat, 12 Mar 2016 04:40:18 +0100 Subject: [PATCH] [Form] add the 'force_submit' option in FormType MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit related to symfony/symfony#18053 Document the new option ‘force_submit’ added to FormType in 3.1 It allows request handlers to submit data that does not hold the form name. --- reference/forms/types/form.rst | 57 ++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/reference/forms/types/form.rst b/reference/forms/types/form.rst index 448e110bd40..47c80ec4c04 100644 --- a/reference/forms/types/form.rst +++ b/reference/forms/types/form.rst @@ -19,6 +19,7 @@ on all types for which ``FormType`` is the parent. | | - `error_bubbling`_ | | | - `error_mapping`_ | | | - `extra_fields_message`_ | +| | - `force_submit`_ | | | - `inherit_data`_ | | | - `invalid_message`_ | | | - `invalid_message_parameters`_ | @@ -94,6 +95,62 @@ The actual default value of this option depends on other field options: .. include:: /reference/forms/types/options/extra_fields_message.rst.inc +force_submit +~~~~~~~~~~~~ + +.. versionadded:: 3.1 + The ``force_submit`` option was introduced in Symfony 3.1. + +**type**: ``bool`` **default**: ``false`` + +By default when an array of data is built from request parameters in a +:class:`Symfony\\Component\\Form\\RequestHandlerInterface` the name of the form +must match a parameter key so the data can be submitted to it. + +This option allow request handlers to force the submission of data to a form +when its name is not among the request parameters. + +.. code-block:: php + + // Normal submission + $request->request->set('my_form' => array( + 'name' => 'John Doe', + 'email' => 'john@foo.com', + ), + ); + + $form = $formFactory->createNamedBuilder('my_form') + ->add('name') + ->add('email', EmailType::class) + ->getForm(); + + $form->handleRequest($request); + + // Forced submission + $request->request->set('name', 'John Doe'); + $request->request->set('email', 'john@foo.com'); + + $form = $formFactory->createNamedBuilder('my_form', null, array( + 'force_submit' => true, + )) + ->add('name') + ->add('email', EmailType::class) + ->getForm(); + + $form->handleRequest($request); + +.. note:: + + This option is meant to be used with root forms such as default one, + or custom form types. + If this option is true in a nested form or field, it will have no + effect on the submission process. + +.. tip:: + + This can be useful when using an API as you don't need to nest the data + in an array with the form name as key. + .. include:: /reference/forms/types/options/inherit_data.rst.inc .. include:: /reference/forms/types/options/invalid_message.rst.inc