From a5c4a4fe159f75fd17fee42eacaec77b1b4d7e35 Mon Sep 17 00:00:00 2001
From: Christian Flothmann <christian.flothmann@xabbuh.de>
Date: Fri, 13 Sep 2013 11:00:44 +0200
Subject: [PATCH] use handleRequest() instead of bind()

---
 components/form/introduction.rst | 70 ++++++++++++--------------------
 1 file changed, 27 insertions(+), 43 deletions(-)

diff --git a/components/form/introduction.rst b/components/form/introduction.rst
index 90c93ce4dc0..a7f86a86e09 100644
--- a/components/form/introduction.rst
+++ b/components/form/introduction.rst
@@ -66,13 +66,13 @@ factory.
 Request Handling
 ~~~~~~~~~~~~~~~~
 
-To process form data, you'll need to grab information off of the request (typically
-``$_POST`` data) and pass the array of submitted data to
-:method:`Symfony\\Component\\Form\\Form::bind`. The Form component optionally
-integrates with Symfony's :doc:`HttpFoundation </components/http_foundation/introduction>`
-component to make this even easier.
+.. versionadded:: 2.3
+    The ``handleRequest()`` method was added in Symfony 2.3.
 
-To integrate the HttpFoundation component, add the
+To process form data, you'll need to call the :method:`Symfony\\Component\\Form\\Form::handleRequest`
+method.
+
+To optionally integrate the HttpFoundation component, add the
 :class:`Symfony\\Component\\Form\\Extension\\HttpFoundation\\HttpFoundationExtension`
 to your form factory::
 
@@ -84,8 +84,7 @@ to your form factory::
         ->getFormFactory();
 
 Now, when you process a form, you can pass the :class:`Symfony\\Component\\HttpFoundation\\Request`
-object to :method:`Symfony\\Component\\Form\\Form::bind` instead of the raw
-array of submitted values.
+object to :method:`Symfony\\Component\\Form\\Form::handleRequest`.
 
 .. note::
 
@@ -480,7 +479,7 @@ to do that in the ":ref:`form-rendering-template`" section.
 Handling Form Submissions
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To handle form submissions, use the :method:`Symfony\\Component\\Form\\Form::bind`
+To handle form submissions, use the :method:`Symfony\\Component\\Form\\Form::handleRequest`
 method:
 
 .. configuration-block::
@@ -497,19 +496,17 @@ method:
 
         $request = Request::createFromGlobals();
 
-        if ($request->isMethod('POST')) {
-            $form->bind($request);
+        $form->handleRequest($request);
 
-            if ($form->isValid()) {
-                $data = $form->getData();
+        if ($form->isValid()) {
+            $data = $form->getData();
 
-                // ... perform some action, such as saving the data to the database
+            // ... perform some action, such as saving the data to the database
 
-                $response = new RedirectResponse('/task/success');
-                $response->prepare($request);
+            $response = new RedirectResponse('/task/success');
+            $response->prepare($request);
 
-                return $response->send();
-            }
+            return $response->send();
         }
 
         // ...
@@ -525,17 +522,14 @@ method:
                 ->add('dueDate', 'date')
                 ->getForm();
 
-            // only process the form if the request is a POST request
-            if ($request->isMethod('POST')) {
-                $form->bind($request);
+            $form->handleRequest($request);
 
-                if ($form->isValid()) {
-                    $data = $form->getData();
+            if ($form->isValid()) {
+                $data = $form->getData();
 
-                    // ... perform some action, such as saving the data to the database
+                // ... perform some action, such as saving the data to the database
 
-                    return $this->redirect($this->generateUrl('task_success'));
-                }
+                return $this->redirect($this->generateUrl('task_success'));
             }
 
             // ...
@@ -546,25 +540,15 @@ 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),
    build your form and render it;
 
-If the request is a POST, process the submitted data (via ``bind``). Then:
+If the request is a POST, process the submitted data (via ``handleRequest()``).
+Then:
 
-2) if the form is invalid, re-render the form (which will now contain errors)
-3) if the form is valid, perform some action and redirect;
-
-.. note::
-
-    If you're not using HttpFoundation, just pass the POST'ed data directly
-    to ``bind``::
-
-        if (isset($_POST[$form->getName()])) {
-            $form->bind($_POST[$form->getName()]);
-
-            // ...
-        }
+2) if the form is invalid, re-render the form (which will now contain errors);
+3) if the form is valid, perform some action and redirect.
 
-    If you're uploading files, you'll need to do a little bit more work by
-    merging the ``$_POST`` array with the ``$_FILES`` array before passing
-    it into ``bind``.
+Luckily, you don't need to decide whether or not a form has been submitted.
+Just pass the current request to the ``handleRequest()`` method. Then, the Form
+component will do all the necessary work for you.
 
 .. _component-form-intro-validation: