From a30f4a035036c81d37c15e705a5c713636872053 Mon Sep 17 00:00:00 2001 From: Victor Berchet Date: Sun, 27 May 2012 21:41:59 +0200 Subject: [PATCH] [Form] cleanup --- .../EventListener/ValidationListener.php | 6 ++--- src/Symfony/Component/Form/Form.php | 23 ++++++++++--------- src/Symfony/Component/Form/FormConfig.php | 7 +++--- .../Form/FormConfigEditorInterface.php | 16 ++++++++++--- .../Component/Form/FormConfigInterface.php | 4 ++-- .../EventListener/ValidationListenerTest.php | 8 +++---- 6 files changed, 38 insertions(+), 26 deletions(-) diff --git a/src/Symfony/Component/Form/Extension/Validator/EventListener/ValidationListener.php b/src/Symfony/Component/Form/Extension/Validator/EventListener/ValidationListener.php index 6dfd5c2e36..f40ac217ff 100644 --- a/src/Symfony/Component/Form/Extension/Validator/EventListener/ValidationListener.php +++ b/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(); diff --git a/src/Symfony/Component/Form/Form.php b/src/Symfony/Component/Form/Form.php index 0b0b879acc..cc6bedccaf 100644 --- a/src/Symfony/Component/Form/Form.php +++ b/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 - * different representations: + * of the data flow within a form. A form stores its data in three different + * representations: * - * (1) the format required by the form's object - * (2) a normalized format for internal processing - * (3) the format used for display + * (1) the "model" format required by the form's object + * (2) the "normalized" format for internal processing + * (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 - * converted to the displayed data as described before. + * addNormTransformer(). The normalized data is then converted to the displayed + * 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 * @author Bernhard Schussek diff --git a/src/Symfony/Component/Form/FormConfig.php b/src/Symfony/Component/Form/FormConfig.php index 447adc795e..9c0c6c91eb 100644 --- a/src/Symfony/Component/Form/FormConfig.php +++ b/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 $dataClass The class of the form's data. - * @param EventDispatcherInterface $dispatcher The event dispatcher. + * @param string $name The form name + * @param string $dataClass The class of the form's data + * @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 diff --git a/src/Symfony/Component/Form/FormConfigEditorInterface.php b/src/Symfony/Component/Form/FormConfigEditorInterface.php index 2a16de5e5d..7b1dfddac6 100644 --- a/src/Symfony/Component/Form/FormConfigEditorInterface.php +++ b/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 * diff --git a/src/Symfony/Component/Form/FormConfigInterface.php b/src/Symfony/Component/Form/FormConfigInterface.php index ee284bb5fa..d656ef3201 100644 --- a/src/Symfony/Component/Form/FormConfigInterface.php +++ b/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. */ diff --git a/src/Symfony/Component/Form/Tests/Extension/Validator/EventListener/ValidationListenerTest.php b/src/Symfony/Component/Form/Tests/Extension/Validator/EventListener/ValidationListenerTest.php index 5bea8f45d4..e9212f5914 100644 --- a/src/Symfony/Component/Form/Tests/Extension/Validator/EventListener/ValidationListenerTest.php +++ b/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)); } }