Merge branch 'remove-bind' of github.com:bschussek/symfony-docs into bschussek-remove-bind

weaverryan · weaverryan · commit 8a03f2ecb2a2 · 2013-04-26T08:50:53.000-05:00
Conflicts:
	cookbook/form/index.rst
diff --git a/book/forms.rst b/book/forms.rst
@@ -226,8 +226,8 @@ controller::
 .. versionadded:: 2.3
     The :method:`Symfony\Component\Form\FormInterface::handleRequest` method was
     added in Symfony 2.3. Previously, the ``$request`` was passed to the
-    ``bind`` method - a strategy which is deprecated and will be removed
-    in Symfony 3.0. For details on that method, see :doc:`/cookbook/form/direct_bind`.
+    ``submit`` method - a strategy which is deprecated and will be removed
+    in Symfony 3.0. For details on that method, see :doc:`/cookbook/form/direct_submit`.
 
 This controller follows a common pattern for handling forms, and has three
 possible paths:
@@ -247,7 +247,7 @@ possible paths:
 
    .. note::
 
-       You can use the method :method:`Symfony\Component\Form\FormInterface::isBound`
+       You can use the method :method:`Symfony\Component\Form\FormInterface::isSubmitted`
        to check whether a form was submitted, regardless of whether or not the
        submitted data is actually valid.
 
diff --git a/book/validation.rst b/book/validation.rst
@@ -205,8 +205,8 @@ Validation and Forms
 The ``validator`` service can be used at any time to validate any object.
 In reality, however, you'll usually work with the ``validator`` indirectly
 when working with forms. Symfony's form library uses the ``validator`` service
-internally to validate the underlying object after values have been submitted
-and bound. The constraint violations on the object are converted into ``FieldError``
+internally to validate the underlying object after values have been submitted.
+The constraint violations on the object are converted into ``FieldError``
 objects that can easily be displayed with your form. The typical form submission
 workflow looks like the following from inside a controller::
 
diff --git a/cookbook/form/data_transformers.rst b/cookbook/form/data_transformers.rst
@@ -157,7 +157,7 @@ when creating your form. Later, you'll learn how you could create a custom
 
 Cool, you're done! Your user will be able to enter an issue number into the
 text field and it will be transformed back into an Issue object. This means
-that, after a successful bind, the Form framework will pass a real Issue
+that, after a successful submission, the Form framework will pass a real Issue
 object to ``Task::setIssue()`` instead of the issue number.
 
 If the issue isn't found, a form error will be created for that field and
@@ -201,7 +201,7 @@ used directly.
 
 3) **View Data** - This is the format that's used to fill in the form fields
 themselves. It's also the format in which the user will submit the data. When
-you call ``Form::bind($data)``, the ``$data`` is in the "view" data format.
+you call ``Form::submit($data)``, the ``$data`` is in the "view" data format.
 
 The 2 different types of transformers help convert to and from each of these
 types of data:
diff --git a/cookbook/form/direct_submit.rst b/cookbook/form/direct_submit.rst
@@ -1,8 +1,8 @@
 .. index::
-   single: Form; Form::bind
+   single: Form; Form::submit()
 
-How to use the bind Function to handle Form Submissions
-=======================================================
+How to use the submit() Function to handle Form Submissions
+===========================================================
 
 In Symfony 2.3, a new :method:`Symfony\Component\Form\FormInterface::handleRequest`
 method was added, which makes handling form submissions easier than ever::
@@ -33,11 +33,14 @@ method was added, which makes handling form submissions easier than ever::
 
     To see more about this method, read :ref:`book-form-handling-form-submissions`.
 
-Using Form::bind() to handle a request (deprecated)
----------------------------------------------------
+Calling Form::submit() manually
+-------------------------------
 
-Prior to this, the :method:`Symfony\Component\Form\FormInterface::bind` method
-was used instead::
+In some cases, you want better control over when exactly your form is submitted
+and what data is passed to it. Instead of using the
+:method:`Symfony\Component\Form\FormInterface::handleRequest`
+method, pass the submitted data directly to
+:method:`Symfony\Component\Form\FormInterface::submit`::
 
     use Symfony\Component\HttpFoundation\Request;
     // ...
@@ -49,7 +52,7 @@ was used instead::
             ->getForm();
 
         if ($request->isMethod('POST')) {
-            $form->bind($request);
+            $form->submit($request->request->get($form->getName()));
 
             if ($form->isValid()) {
                 // perform some action...
@@ -63,17 +66,21 @@ was used instead::
         ));
     }
 
-Passing the :class:`Symfony\\Component\HttpFoundation\\Request` directly to
-``bind`` still works, but is deprecated and will be removed in Symfony 3.0.
-However, you *can* safely pass array values directly to bind.
+.. tip::
+
+    Forms consisting of nested fields expect an array in
+    :method:`Symfony\Component\Form\FormInterface::submit`. You can also submit
+    individual fields by calling :method:`Symfony\Component\Form\FormInterface::submit`
+    directly on the field::
 
-Passing an Array directly to Form::bind
----------------------------------------
+        $form->get('firstName')->submit('Fabien');
 
-In some cases, you may want to collect and pass an array of values directly
-to a Form, instead of using the ``handleRequest`` method. This is absolutely
-valid and not deprecated (passing a :class:`Symfony\\Component\HttpFoundation\\Request`
-object to ``Form::bind`` is deprecated, but passing an array of ok)::
+Passing a Request to Form::submit() (deprecated)
+------------------------------------------------
+
+Before Symfony 2.3, the :method:`Symfony\Component\Form\FormInterface::submit`
+method accepted a :class:`Symfony\\Component\\HttpFoundation\\Reuqest` object as
+a convenient shortcut to the previous example::
 
     use Symfony\Component\HttpFoundation\Request;
     // ...
@@ -85,7 +92,7 @@ object to ``Form::bind`` is deprecated, but passing an array of ok)::
             ->getForm();
 
         if ($request->isMethod('POST')) {
-            $form->bind($request->request->get($form->getName()));
+            $form->submit($request);
 
             if ($form->isValid()) {
                 // perform some action...
@@ -98,3 +105,8 @@ object to ``Form::bind`` is deprecated, but passing an array of ok)::
             'form' => $form->createView(),
         ));
     }
+
+Passing the :class:`Symfony\\Component\HttpFoundation\\Request` directly to
+:method:`Symfony\\Component\\Form\\FormInterface::submit`` still works, but is
+deprecated and will be removed in Symfony 3.0. You should use the method
+:method:`Symfony\Component\Form\FormInterface::handleRequest` instead.
diff --git a/cookbook/form/dynamic_form_modification.rst b/cookbook/form/dynamic_form_modification.rst
@@ -444,14 +444,18 @@ On a form, we can usually listen to the following events:
 
 * ``PRE_SET_DATA``
 * ``POST_SET_DATA``
-* ``PRE_BIND``
-* ``BIND``
-* ``POST_BIND``
+* ``PRE_SUBMIT``
+* ``SUBMIT``
+* ``POST_SUBMIT``
 
-When listening to ``BIND`` and ``POST_BIND``, it's already "too late" to make
-changes to the form. Fortunately, ``PRE_BIND`` is perfect for this. There
+.. versionadded:: 2.3
+    The events ``PRE_SUBMIT``, ``SUBMIT`` and ``POST_SUBMIT`` were added in
+    Symfony 2.3. Before, they were named ``PRE_BIND``, ``BIND`` and ``POST_BIND``.
+
+When listening to ``SUBMIT`` and ``POST_SUBMIT``, it's already "too late" to make
+changes to the form. Fortunately, ``PRE_SUBMIT`` is perfect for this. There
 is, however, a big difference in what ``$event->getData()`` returns for each
-of these events. Specifically, in ``PRE_BIND``, ``$event->getData()`` returns
+of these events. Specifically, in ``PRE_SUBMIT``, ``$event->getData()`` returns
 the raw data submitted by the user.
 
 This can be used to get the ``SportMeetup`` id and retrieve it from the database,
@@ -494,7 +498,7 @@ The subscriber would now look like::
         public static function getSubscribedEvents()
         {
             return array(
-                FormEvents::PRE_BIND => 'preBind',
+                FormEvents::PRE_SUBMIT => 'preSubmit',
                 FormEvents::PRE_SET_DATA => 'preSetData',
             );
         }
@@ -506,7 +510,7 @@ The subscriber would now look like::
         {
             $meetup = $event->getData()->getMeetup();
 
-            // Before binding the form, the "meetup" will be null
+            // Before SUBMITing the form, the "meetup" will be null
             if (null === $meetup) {
                 return;
             }
@@ -517,7 +521,7 @@ The subscriber would now look like::
             $this->customizeForm($form, $positions);
         }
 
-        public function preBind(FormEvent $event)
+        public function preSubmit(FormEvent $event)
         {
             $data = $event->getData();
             $id = $data['event'];
@@ -617,6 +621,6 @@ set for every possible kind of sport that our users are registering for.
 
 One piece that may still be missing is the client-side updating of your form
 after the sport is selected. This should be handled by making an AJAX call
-back to your application. In that controller, you can bind your form, but
-instead of processing it, simply use the bound form to render the updated
+back to your application. In that controller, you can submit your form, but
+instead of processing it, simply use the submitted form to render the updated
 fields. The response from the AJAX call can then be used to update the view.
diff --git a/cookbook/form/index.rst b/cookbook/form/index.rst
@@ -13,6 +13,4 @@ Form
     inherit_data_option
     unit_testing
     use_empty_data
-    direct_bind
-
-
+    direct_submit
diff --git a/cookbook/form/unit_testing.rst b/cookbook/form/unit_testing.rst
@@ -40,7 +40,7 @@ The simplest ``TypeTestCase`` implementation looks like the following::
 
     class TestedTypeTest extends TypeTestCase
     {
-        public function testBindValidData()
+        public function testSubmitValidData()
         {
             $formData = array(
                 'test' => 'test',
@@ -53,8 +53,8 @@ The simplest ``TypeTestCase`` implementation looks like the following::
             $object = new TestObject();
             $object->fromArray($formData);
 
-            // bind the data to the form directly
-            $form->bind($formData);
+            // submit the data to the form directly
+            $form->submit($formData);
 
             $this->assertTrue($form->isSynchronized());
             $this->assertEquals($object, $form->getData());
@@ -81,7 +81,7 @@ This test checks that none of your data transformers used by the form
 failed. The :method:`Symfony\\Component\\Form\\FormInterface::isSynchronized``
 method is only set to ``false`` if a data transformer throws an exception::
 
-    $form->bind($formData);
+    $form->submit($formData);
     $this->assertTrue($form->isSynchronized());
 
 .. note::
@@ -90,7 +90,7 @@ method is only set to ``false`` if a data transformer throws an exception::
     active in the test case and it relies on validation configuration.
     Instead, unit test your custom constraints directly.
 
-Next, verify the binding and mapping of the form. The test below
+Next, verify the submission and mapping of the form. The test below
 checks if all the fields are correctly specified::
 
     $this->assertEquals($object, $form->getData());
@@ -129,7 +129,7 @@ before creating the parent form::
 
     class TestedTypeTest extends TypeTestCase
     {
-        public function testBindValidData()
+        public function testSubmitValidData()
         {
             $this->factory->addType(new TestChildType());
 
diff --git a/cookbook/form/use_empty_data.rst b/cookbook/form/use_empty_data.rst
@@ -5,7 +5,7 @@ How to configure Empty Data for a Form Class
 ============================================
 
 The ``empty_data`` option allows you to specify an empty data set for your
-form class. This empty data set would be used if you bind your form, but
+form class. This empty data set would be used if you submit your form, but
 haven't called ``setData()`` on your form or passed in data when you created
 you form. For example::
 
diff --git a/cookbook/security/acl.rst b/cookbook/security/acl.rst
@@ -102,7 +102,7 @@ Creating an ACL, and adding an ACE
         {
             $comment = new Comment();
 
-            // ... setup $form, and bind data
+            // ... setup $form, and submit data
 
             if ($form->isValid()) {
                 $entityManager = $this->getDoctrine()->getManager();
diff --git a/reference/forms/types/url.rst b/reference/forms/types/url.rst
@@ -36,7 +36,7 @@ default_protocol
 
 If a value is submitted that doesn't begin with some protocol (e.g. ``http://``,
 ``ftp://``, etc), this protocol will be prepended to the string when
-the data is bound to the form.
+the data is submitted to the form.
 
 Inherited Options
 -----------------

Original file line number	Diff line number	Diff line change
`@@ -102,7 +102,7 @@ Creating an ACL, and adding an ACE`
`102`	`102`	`{`
`103`	`103`	`$comment = new Comment();`
`104`	`104`
`105`		`- // ... setup $form, and bind data`
	`105`	`+ // ... setup $form, and submit data`
`106`	`106`
`107`	`107`	`if ($form->isValid()) {`
`108`	`108`	`$entityManager = $this->getDoctrine()->getManager();`