Merge pull request #42 from sensiolabs/issue-10-form

split the Forms chapter

Author: weaverryan

cache/form_csrf_caching.rst

@@ -8,7 +8,7 @@ CSRF tokens are meant to be different for every user. This is why you
 need to be cautious if you try to cache pages with forms including them.
 
 For more information about how CSRF protection works in Symfony, please
-check :ref:`CSRF Protection <forms-csrf>`.
+check :doc:`CSRF Protection </form/csrf_protection>`.
 
 Why Caching Pages with a CSRF token is Problematic
 --------------------------------------------------

cache/varnish.rst

@@ -77,7 +77,7 @@ If you know for sure that the backend never uses sessions or basic
 authentication, have Varnish remove the corresponding header from requests to
 prevent clients from bypassing the cache. In practice, you will need sessions
 at least for some parts of the site, e.g. when using forms with
-:ref:`CSRF Protection <forms-csrf>`. In this situation, make sure to
+:doc:`CSRF Protection </form/csrf_protection>`. In this situation, make sure to
 :doc:`only start a session when actually needed </session/avoid_session_start>`
 and clear the session when it is no longer needed. Alternatively, you can look
 into :doc:`/cache/form_csrf_caching`.

components/form.rst

@@ -498,7 +498,7 @@ That's it! By printing ``form_widget(form)``, each field in the form is
 rendered, along with a label and error message (if there is one). As easy
 as this is, it's not very flexible (yet). Usually, you'll want to render each
 form field individually so you can control how the form looks. You'll learn how
-to do that in the ":ref:`form-rendering-template`" section.
+to do that in the ":doc:`/form/rendering`" section.
 
 Changing a Form's Method and Action
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

form/action_method.rst

@@ -0,0 +1,63 @@
+.. index::
+    single: Forms; Changing the action and method
+
+How to Change the Action and Method of a Form
+=============================================
+
+By default, a form will be submitted via an HTTP POST request to the same
+URL under which the form was rendered. Sometimes you want to change these
+parameters. You can do so in a few different ways.
+
+If you use the :class:`Symfony\\Component\\Form\\FormBuilder` to build your
+form, you can use ``setAction()`` and ``setMethod()``::
+
+    $form = $this->createFormBuilder($task)
+        ->setAction($this->generateUrl('target_route'))
+        ->setMethod('GET')
+        ->add('task', 'text')
+        ->add('dueDate', 'date')
+        ->add('save', 'submit')
+        ->getForm();
+
+.. note::
+
+    This example assumes that you've created a route called ``target_route``
+    that points to the controller that processes the form.
+
+When using a form type class, you can pass the action and method as form
+options::
+
+    use AppBundle\Form\TaskType;
+    // ...
+
+    $form = $this->createForm(new TaskType(), $task, array(
+        'action' => $this->generateUrl('target_route'),
+        'method' => 'GET',
+    ));
+
+Finally, you can override the action and method in the template by passing them
+to the ``form()`` or the ``form_start()`` helper functions:
+
+.. configuration-block::
+
+    .. code-block:: html+twig
+
+        {# app/Resources/views/default/new.html.twig #}
+        {{ form_start(form, {'action': path('target_route'), 'method': 'GET'}) }}
+
+    .. code-block:: html+php
+
+        <!-- app/Resources/views/default/newAction.html.php -->
+        <?php echo $view['form']->start($form, array(
+            'action' => $view['router']->generate('target_route'),
+            'method' => 'GET',
+        )) ?>
+
+.. note::
+
+    If the form's method is not GET or POST, but PUT, PATCH or DELETE, Symfony
+    will insert a hidden field with the name ``_method`` that stores this method.
+    The form will be submitted in a normal POST request, but Symfony's router
+    is capable of detecting the ``_method`` parameter and will interpret it as
+    a PUT, PATCH or DELETE request. Read the cookbook chapter
+    ":doc:`/routing/method_parameters`" for more information.

form/button_based_validation.rst

@@ -0,0 +1,43 @@
+.. index::
+    single: Forms; Validation groups based on clicked button
+
+How to Choose Validation Groups Based on the Clicked Button
+===========================================================
+
+.. versionadded:: 2.3
+    Support for buttons in forms was introduced in Symfony 2.3.
+
+When your form contains multiple submit buttons, you can change the validation
+group depending on which button is used to submit the form. For example,
+consider a form in a wizard that lets you advance to the next step or go back
+to the previous step. Also assume that when returning to the previous step,
+the data of the form should be saved, but not validated.
+
+First, we need to add the two buttons to the form::
+
+    $form = $this->createFormBuilder($task)
+        // ...
+        ->add('nextStep', 'submit')
+        ->add('previousStep', 'submit')
+        ->getForm();
+
+Then, we configure the button for returning to the previous step to run
+specific validation groups. In this example, we want it to suppress validation,
+so we set its ``validation_groups`` option to false::
+
+    $form = $this->createFormBuilder($task)
+        // ...
+        ->add('previousStep', 'submit', array(
+            'validation_groups' => false,
+        ))
+        ->getForm();
+
+Now the form will skip your validation constraints. It will still validate
+basic integrity constraints, such as checking whether an uploaded file was too
+large or whether you tried to submit text in a number field.
+
+.. seealso::
+
+    To see how to use a service to resolve ``validation_groups`` dynamically
+    read the :doc:`/validation/group_service_resolver`
+    chapter in the cookbook.

form/csrf_protection.rst

@@ -0,0 +1,72 @@
+.. index::
+    single: Forms; CSRF protection
+
+How to Implement CSRF Protection
+================================
+
+CSRF - or `Cross-site request forgery`_ - is a method by which a malicious
+user attempts to make your legitimate users unknowingly submit data that
+they don't intend to submit. Fortunately, CSRF attacks can be prevented by
+using a CSRF token inside your forms.
+
+The good news is that, by default, Symfony embeds and validates CSRF tokens
+automatically for you. This means that you can take advantage of the CSRF
+protection without doing anything. In fact, every form in this chapter has
+taken advantage of the CSRF protection!
+
+CSRF protection works by adding a hidden field to your form - called ``_token``
+by default - that contains a value that only you and your user knows. This
+ensures that the user - not some other entity - is submitting the given data.
+Symfony automatically validates the presence and accuracy of this token.
+
+The ``_token`` field is a hidden field and will be automatically rendered
+if you include the ``form_end()`` function in your template, which ensures
+that all un-rendered fields are output.
+
+.. caution::
+
+    Since the token is stored in the session, a session is started automatically
+    as soon as you render a form with CSRF protection.
+
+The CSRF token can be customized on a form-by-form basis. For example::
+
+    use Symfony\Component\OptionsResolver\OptionsResolver;
+
+    class TaskType extends AbstractType
+    {
+        // ...
+
+        public function configureOptions(OptionsResolver $resolver)
+        {
+            $resolver->setDefaults(array(
+                'data_class'      => 'AppBundle\Entity\Task',
+                'csrf_protection' => true,
+                'csrf_field_name' => '_token',
+                // a unique key to help generate the secret token
+                'csrf_token_id'   => 'task_item',
+            ));
+        }
+
+        // ...
+    }
+
+.. _form-disable-csrf:
+
+To disable CSRF protection, set the ``csrf_protection`` option to false.
+Customizations can also be made globally in your project. For more information,
+see the :ref:`form configuration reference <reference-framework-form>`
+section.
+
+.. note::
+
+    The ``csrf_token_id`` option is optional but greatly enhances the security
+    of the generated token by making it different for each form.
+
+.. caution::
+
+    CSRF tokens are meant to be different for every user. This is why you
+    need to be cautious if you try to cache pages with forms including this
+    kind of protection. For more information, see
+    :doc:`/cache/form_csrf_caching`.
+
+.. _`Cross-site request forgery`: http://en.wikipedia.org/wiki/Cross-site_request_forgery

form/data_based_validation.rst

@@ -0,0 +1,74 @@
+.. index::
+    single: Forms; Validation groups based on submitted data
+
+How to Choose Validation Groups Based on the Submitted Data
+===========================================================
+
+If you need some advanced logic to determine the validation groups (e.g.
+based on submitted data), you can set the ``validation_groups`` option
+to an array callback::
+
+    use Symfony\Component\OptionsResolver\OptionsResolver;
+
+    // ...
+    public function configureOptions(OptionsResolver $resolver)
+    {
+        $resolver->setDefaults(array(
+            'validation_groups' => array(
+                'AppBundle\Entity\Client',
+                'determineValidationGroups',
+            ),
+        ));
+    }
+
+This will call the static method ``determineValidationGroups()`` on the
+``Client`` class after the form is submitted, but before validation is executed.
+The Form object is passed as an argument to that method (see next example).
+You can also define whole logic inline by using a ``Closure``::
+
+    use AppBundle\Entity\Client;
+    use Symfony\Component\Form\FormInterface;
+    use Symfony\Component\OptionsResolver\OptionsResolver;
+
+    // ...
+    public function configureOptions(OptionsResolver $resolver)
+    {
+        $resolver->setDefaults(array(
+            'validation_groups' => function (FormInterface $form) {
+                $data = $form->getData();
+
+                if (Client::TYPE_PERSON == $data->getType()) {
+                    return array('person');
+                }
+
+                return array('company');
+            },
+        ));
+    }
+
+Using the ``validation_groups`` option overrides the default validation
+group which is being used. If you want to validate the default constraints
+of the entity as well you have to adjust the option as follows::
+
+    use AppBundle\Entity\Client;
+    use Symfony\Component\Form\FormInterface;
+    use Symfony\Component\OptionsResolver\OptionsResolver;
+
+    // ...
+    public function configureOptions(OptionsResolver $resolver)
+    {
+        $resolver->setDefaults(array(
+            'validation_groups' => function (FormInterface $form) {
+                $data = $form->getData();
+
+                if (Client::TYPE_PERSON == $data->getType()) {
+                    return array('Default', 'person');
+                }
+
+                return array('Default', 'company');
+            },
+        ));
+    }
+
+You can find more information about how the validation groups and the default constraints
+work in the book section about :doc:`validation groups </validation/groups>`.

form/data_transformers.rst

@@ -289,7 +289,7 @@ Now, when you create your ``TaskType``, you'll need to pass in the entity manage
 .. note::
 
     To make this step easier (especially if ``TaskType`` is embedded into other
-    form type classes), you might choose to :ref:`register your form type as a service <form-as-services>`.
+    form type classes), you might choose to :doc:`register your form type as a service </form/form_dependencies>`.
 
 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

form/disabling_validation.rst

@@ -0,0 +1,25 @@
+.. index::
+    single: Forms; Disabling validation
+
+How to Disable the Validation of Submitted Data
+===============================================
+
+.. versionadded:: 2.3
+    The ability to set ``validation_groups`` to false was introduced in Symfony 2.3.
+
+Sometimes it is useful to suppress the validation of a form altogether. For
+these cases you can set the ``validation_groups`` option to ``false``::
+
+    use Symfony\Component\OptionsResolver\OptionsResolver;
+
+    public function configureOptions(OptionsResolver $resolver)
+    {
+        $resolver->setDefaults(array(
+            'validation_groups' => false,
+        ));
+    }
+
+Note that when you do that, the form will still run basic integrity checks,
+for example whether an uploaded file was too large or whether non-existing
+fields were submitted. If you want to suppress validation, you can use the
+:ref:`POST_SUBMIT event <cookbook-dynamic-form-modification-suppressing-form-validation>`.