Merge branch '5.3' into 5.4

* 5.3:
  Replace render by new renderForm method in form documentation

Author: javiereguiluz

components/form.rst

@@ -647,6 +647,12 @@ method:
             }
         }
 
+.. caution::
+
+    The form's ``createView()`` method should be called *after* ``handleRequest()`` is
+    called. Otherwise, when using :doc:`form events </form/events>`, changes done
+    in the ``*_SUBMIT`` events won't be applied to the view (like validation errors).
+
 This defines a common form "workflow", which contains 3 different possibilities:
 
 1) On the initial GET request (i.e. when the user "surfs" to your page),

controller/upload_file.rst

@@ -174,8 +174,8 @@ Finally, you need to update the code of the controller that handles the form::
                 return $this->redirectToRoute('app_product_list');
             }
 
-            return $this->render('product/new.html.twig', [
-                'form' => $form->createView(),
+            return $this->renderForm('product/new.html.twig', [
+                'form' => $form,
             ]);
         }
     }

form/direct_submit.rst

@@ -29,8 +29,8 @@ control over when exactly your form is submitted and what data is passed to it::
             }
         }
 
-        return $this->render('task/new.html.twig', [
-            'form' => $form->createView(),
+        return $this->renderForm('task/new.html.twig', [
+            'form' => $form,
         ]);
     }
 

form/dynamic_form_modification.rst

@@ -534,10 +534,9 @@ your application. Assume that you have a sport meetup creation controller::
                 // ... save the meetup, redirect etc.
             }
 
-            return $this->render(
-                'meetup/create.html.twig',
-                ['form' => $form->createView()]
-            );
+            return $this->renderForm('meetup/create.html.twig', [
+                'form' => $form,
+            ]);
         }
 
         // ...

form/form_collections.rst

@@ -164,8 +164,8 @@ In your controller, you'll create a new form from the ``TaskType``::
                 // ... do your form processing, like saving the Task and Tag entities
             }
 
-            return $this->render('task/new.html.twig', [
-                'form' => $form->createView(),
+            return $this->renderForm('task/new.html.twig', [
+                'form' => $form,
             ]);
         }
     }

form/form_customization.rst

@@ -20,8 +20,9 @@ enough to render an entire form, including all its fields and error messages:
 
 .. code-block:: twig
 
-    {# form is a variable passed from the controller and created
-      by calling to the $form->createView() method #}
+    {# form is a variable passed from the controller via either
+      $this->renderForm('...', ['form' => $form])
+      or $this->render('...', ['form' => $form->createView()]) #}
     {{ form(form) }}
 
 The next step is to use the :ref:`form_start() <reference-forms-twig-start>`,

forms.rst

@@ -255,9 +255,7 @@ the ``data_class`` option by adding the following to your form type class::
 Rendering Forms
 ---------------
 
-Now that the form has been created, the next step is to render it. Instead of
-passing the entire form object to the template, use the ``createView()`` method
-to build another object with the visual representation of the form::
+Now that the form has been created, the next step is to render it::
 
     // src/Controller/TaskController.php
     namespace App\Controller;
@@ -277,12 +275,21 @@ to build another object with the visual representation of the form::
 
             $form = $this->createForm(TaskType::class, $task);
 
-            return $this->render('task/new.html.twig', [
-                'form' => $form->createView(),
+            return $this->renderForm('task/new.html.twig', [
+                'form' => $form,
             ]);
         }
     }
 
+In versions prior to Symfony 5.3, controllers used the method
+``$this->render('...', ['form' => $form->createView()])`` to render the form.
+The ``renderForm()`` method abstracts this logic and it also sets the 422 HTTP
+status code in the response automatically when the submitted form is not valid.
+
+.. versionadded:: 5.3
+
+    The ``renderForm()`` method was introduced in Symfony 5.3.
+
 Then, use some :ref:`form helper functions <reference-form-twig-functions>` to
 render the form contents:
 
@@ -401,8 +408,8 @@ written into the form object::
                 return $this->redirectToRoute('task_success');
             }
 
-            return $this->render('task/new.html.twig', [
-                'form' => $form->createView(),
+            return $this->renderForm('task/new.html.twig', [
+                'form' => $form,
             ]);
         }
     }
@@ -433,12 +440,6 @@ possible paths:
     that prevents the user from being able to hit the "Refresh" button of
     their browser and re-post the data.
 
-.. caution::
-
-    The ``createView()`` method should be called *after* ``handleRequest()`` is
-    called. Otherwise, when using :doc:`form events </form/events>`, changes done
-    in the ``*_SUBMIT`` events won't be applied to the view (like validation errors).
-
 .. seealso::
 
     If you need more control over exactly when your form is submitted or which