[Form] cleanup

src/Symfony/Component/Form/Extension/Validator/EventListener/ValidationListener.php

@@ -15,7 +15,7 @@ use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 use Symfony\Component\Form\Extension\Validator\ViolationMapper\ViolationMapperInterface;
 use Symfony\Component\Validator\ValidatorInterface;
 use Symfony\Component\Form\FormEvents;
-use Symfony\Component\Form\Event\DataEvent;
+use Symfony\Component\Form\FormEvent;
 use Symfony\Component\Form\Extension\Validator\Constraints\Form;
 
 /**
@@ -44,9 +44,9 @@ class ValidationListener implements EventSubscriberInterface
     /**
      * Validates the form and its domain object.
      *
-     * @param DataEvent $event The event object
+     * @param FormEvent $event The event object
      */
-    public function validateForm(DataEvent $event)
+    public function validateForm(FormEvent $event)
     {
         $form = $event->getForm();
 

src/Symfony/Component/Form/Form.php

@@ -22,15 +22,13 @@ use Symfony\Component\EventDispatcher\EventDispatcherInterface;
 /**
  * Form represents a form.
  *
- * A form is composed of a validator schema and a widget form schema.
- *
  * 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
+ * of the data flow within a form. A form stores its data in three different
- * different representations:
+ * representations:
  *
- *   (1) the format required by the form's object
+ *   (1) the "model" format required by the form's object
- *   (2) a normalized format for internal processing
+ *   (2) the "normalized" format for internal processing
- *   (3) the format used for display
+ *   (3) the "view" format used for display
  *
  * A date field, for example, may store a date as "Y-m-d" string (1) in the
  * object. To facilitate processing in the field, this value is normalized
@@ -38,18 +36,21 @@ use Symfony\Component\EventDispatcher\EventDispatcherInterface;
  * localized string (3) is presented to and modified by the user.
  *
  * In most cases, format (1) and format (2) will be the same. For example,
- * a checkbox field uses a Boolean value both for internal processing as for
+ * a checkbox field uses a Boolean value for both internal processing and
  * storage in the object. In these cases you simply need to set a value
  * transformer to convert between formats (2) and (3). You can do this by
- * calling appendClientTransformer().
+ * calling addViewTransformer().
  *
  * In some cases though it makes sense to make format (1) configurable. To
  * demonstrate this, let's extend our above date field to store the value
  * either as "Y-m-d" string or as timestamp. Internally we still want to
  * use a DateTime object for processing. To convert the data from string/integer
  * to DateTime you can set a normalization transformer by calling
- * appendNormTransformer(). The normalized data is then
+ * addNormTransformer(). The normalized data is then converted to the displayed
- * converted to the displayed data as described before.
+ * data as described before.
+ *
+ * The conversions (1) -> (2) -> (3) use the transform methods of the transformers.
+ * The conversions (3) -> (2) -> (1) use the reverseTransform methods of the transformers.
  *
  * @author Fabien Potencier <fabien@symfony.com>
  * @author Bernhard Schussek <bschussek@gmail.com>

src/Symfony/Component/Form/FormConfig.php

@@ -121,9 +121,10 @@ class FormConfig implements FormConfigEditorInterface
     /**
      * Creates an empty form configuration.
      *
-     * @param  string                   $name       The form name.
+     * @param string                   $name       The form name
-     * @param  string                   $dataClass  The class of the form's data.
+     * @param string                   $dataClass  The class of the form's data
-     * @param  EventDispatcherInterface $dispatcher The event dispatcher.
+     * @param EventDispatcherInterface $dispatcher The event dispatcher
+     * @param array                    $options    The form options
      *
      * @throws UnexpectedTypeException   If the name is not a string.
      * @throws \InvalidArgumentException If the data class is not a valid class or if

src/Symfony/Component/Form/FormConfigEditorInterface.php

@@ -52,7 +52,12 @@ interface FormConfigEditorInterface extends FormConfigInterface
     function addValidator(FormValidatorInterface $validator);
 
     /**
-     * Appends a transformer to the client transformer chain
+     * Appends a transformer to the view transformer chain.
+     *
+     * The transform method of the transformer is used to convert data from the
+     * normalized to the view format.
+     * The reverseTransform method of the transformer is used to convert from the
+     * view to the normalized format.
      *
      * @param DataTransformerInterface $viewTransformer
      *
@@ -61,14 +66,19 @@ interface FormConfigEditorInterface extends FormConfigInterface
     function addViewTransformer(DataTransformerInterface $viewTransformer);
 
     /**
-     * Clears the client transformers.
+     * Clears the view transformers.
      *
      * @return self The configuration object.
      */
     function resetViewTransformers();
 
     /**
-     * Prepends a transformer to the normalization transformer chain
+     * Prepends a transformer to the normalization transformer chain.
+     *
+     * The transform method of the transformer is used to convert data from the
+     * model to the normalized format.
+     * The reverseTransform method of the transformer is used to convert from the
+     * normalized to the model format.
      *
      * @param DataTransformerInterface $modelTransformer
      *

src/Symfony/Component/Form/FormConfigInterface.php

@@ -73,14 +73,14 @@ interface FormConfigInterface
     function getTypes();
 
     /**
-     * Returns the client transformers of the form.
+     * Returns the view transformers of the form.
      *
      * @return array An array of {@link DataTransformerInterface} instances.
      */
     function getViewTransformers();
 
     /**
-     * Returns the view transformers of the form.
+     * Returns the model transformers of the form.
      *
      * @return array An array of {@link DataTransformerInterface} instances.
      */

src/Symfony/Component/Form/Tests/Extension/Validator/EventListener/ValidationListenerTest.php

@@ -11,7 +11,7 @@
 
 namespace Symfony\Component\Form\Tests\Extension\Validator\EventListener;
 
-use Symfony\Component\Form\Event\DataEvent;
+use Symfony\Component\Form\FormEvent;
 use Symfony\Component\Form\FormInterface;
 use Symfony\Component\Form\FormBuilder;
 use Symfony\Component\Form\FormError;
@@ -114,7 +114,7 @@ class ValidationListenerTest extends \PHPUnit_Framework_TestCase
             ->method('mapViolation')
             ->with($violation, $form, false);
 
-        $this->listener->validateForm(new DataEvent($form, null));
+        $this->listener->validateForm(new FormEvent($form, null));
     }
 
     public function testMapViolationAllowsNonSyncIfInvalid()
@@ -131,7 +131,7 @@ class ValidationListenerTest extends \PHPUnit_Framework_TestCase
             // pass true now
             ->with($violation, $form, true);
 
-        $this->listener->validateForm(new DataEvent($form, null));
+        $this->listener->validateForm(new FormEvent($form, null));
     }
 
     public function testValidateIgnoresNonRoot()
@@ -147,6 +147,6 @@ class ValidationListenerTest extends \PHPUnit_Framework_TestCase
         $this->violationMapper->expects($this->never())
             ->method('mapViolation');
 
-        $this->listener->validateForm(new DataEvent($form, null));
+        $this->listener->validateForm(new FormEvent($form, null));
     }
 }