[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,20 +61,31 @@ class CsrfType extends AbstractType
         ;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function getDefaultOptions(array $options)
     {
         return array(
             'csrf_provider' => $this->csrfProvider,
-            'intention' => null,
+            'intention'     => null,
             'property_path' => false,
         );
     }
 
+    /**
+     * {@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)
-                ->setAttribute('csrf_field_name', $options['csrf_field_name']);
+            $builder
+                ->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,16 +66,22 @@ class FormTypeCsrfExtension extends AbstractTypeExtension
         }
     }
 
+    /**
+     * {@inheritDoc}
+     */
     public function getDefaultOptions(array $options)
     {
         return array(
-            'csrf_protection' => $this->enabled,
-            'csrf_field_name' => $this->fieldName,
-            'csrf_provider'   => null,
-            'intention'  => 'unknown',
+            'csrf_protection'   => $this->enabled,
+            'csrf_field_name'   => $this->fieldName,
+            'csrf_provider'     => null,
+            'intention'         => 'unknown',
         );
     }
 
+    /**
+     * {@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: