[Form] CSRF documentation and a few CS changes

src/Symfony/Component/Form/Extension/Csrf/CsrfExtension.php

@@ -15,15 +15,26 @@ use Symfony\Component\Form\Extension\Csrf\Type;
 use Symfony\Component\Form\Extension\Csrf\CsrfProvider\CsrfProviderInterface;
 use Symfony\Component\Form\AbstractExtension;
 
+/**
+ * This extension protects forms by using a CSRF token
+ */
 class CsrfExtension extends AbstractExtension
 {
     private $csrfProvider;
 
+    /**
+     * Constructor.
+     *
+     * @param CsrfProviderInterface $csrfProvider The CSRF provider
+     */
     public function __construct(CsrfProviderInterface $csrfProvider)
     {
         $this->csrfProvider = $csrfProvider;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     protected function loadTypes()
     {
         return array(
@@ -31,6 +42,9 @@ class CsrfExtension extends AbstractExtension
         );
     }
 
+    /**
+     * {@inheritDoc}
+     */
     protected function loadTypeExtensions()
     {
         return array(

src/Symfony/Component/Form/Extension/Csrf/Type/CsrfType.php

@@ -22,11 +22,25 @@ class CsrfType extends AbstractType
 {
     private $csrfProvider;
 
+    /**
+     * Constructor.
+     *
+     * @param CsrfProviderInterface $csrfProvider The provider to use to generate the token
+     */
     public function __construct(CsrfProviderInterface $csrfProvider)
     {
         $this->csrfProvider = $csrfProvider;
     }
 
+    /**
+     * Builds the CSRF field.
+     *
+     * A validator is added to check the token value when the CSRF field is added to
+     * a root form
+     *
+     * @param FormBuilder $builder The form builder
+     * @param array       $options The options
+     */
     public function buildForm(FormBuilder $builder, array $options)
     {
         $csrfProvider = $options['csrf_provider'];
@@ -47,6 +61,9 @@ class CsrfType extends AbstractType
         ;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function getDefaultOptions(array $options)
     {
         return array(
@@ -56,11 +73,19 @@ class CsrfType extends AbstractType
         );
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function getParent(array $options)
     {
         return 'hidden';
     }
 
+    /**
+     * Returns the name of this form.
+     *
+     * @return string 'csrf'
+     */
     public function getName()
     {
         return 'csrf';

src/Symfony/Component/Form/Extension/Csrf/Type/FormTypeCsrfExtension.php

@@ -27,6 +27,12 @@ class FormTypeCsrfExtension extends AbstractTypeExtension
         $this->fieldName = $fieldName;
     }
 
+    /**
+     * Adds a CSRF field to the form when the CSRF protection is enabled.
+     *
+     * @param FormBuilder   $builder The form builder
+     * @param array         $options The options
+     */
     public function buildForm(FormBuilder $builder, array $options)
     {
         if ($options['csrf_protection']) {
@@ -36,11 +42,19 @@ class FormTypeCsrfExtension extends AbstractTypeExtension
                 $csrfOptions['csrf_provider'] = $options['csrf_provider'];
             }
 
-            $builder->add($options['csrf_field_name'], 'csrf', $csrfOptions)
+            $builder
-                ->setAttribute('csrf_field_name', $options['csrf_field_name']);
+                ->add($options['csrf_field_name'], 'csrf', $csrfOptions)
+                ->setAttribute('csrf_field_name', $options['csrf_field_name'])
+            ;
         }
     }
 
+    /**
+     * Removes CSRF fields from all the form views except the root one.
+     *
+     * @param FormView      $view The form view
+     * @param FormInterface $form The form
+     */
     public function buildViewBottomUp(FormView $view, FormInterface $form)
     {
         if ($view->hasParent() && $form->hasAttribute('csrf_field_name')) {
@@ -52,6 +66,9 @@ class FormTypeCsrfExtension extends AbstractTypeExtension
         }
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function getDefaultOptions(array $options)
     {
         return array(
@@ -62,6 +79,9 @@ class FormTypeCsrfExtension extends AbstractTypeExtension
         );
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function getExtendedType()
     {
         return 'form';

src/Symfony/Component/Form/Form.php

@@ -24,13 +24,6 @@ use Symfony\Component\EventDispatcher\EventDispatcherInterface;
  *
  * A form is composed of a validator schema and a widget form schema.
  *
- * Form also takes care of CSRF protection by default.
- *
- * A CSRF secret can be any random string. If set to false, it disables the
- * CSRF protection, and if set to null, it forces the form to use the global
- * CSRF secret. If the global CSRF secret is also null, then a random one
- * is generated on the fly.
- *
  * To implement your own form fields, you need to have a thorough understanding
  * of the data flow within a form field. A form field stores its data in three
  * different representations: