[Form] Php doc fixes and cs + optimizations

src/Symfony/Component/Form/AbstractExtension.php

@@ -36,7 +36,7 @@ abstract class AbstractExtension implements FormExtensionInterface
     /**
      * The type guesser provided by this extension.
      *
-     * @var FormTypeGuesserInterface
+     * @var FormTypeGuesserInterface|null
      */
     private $typeGuesser;
 
@@ -136,7 +136,7 @@ protected function loadTypeExtensions()
     /**
      * Registers the type guesser.
      *
-     * @return FormTypeGuesserInterface|null A type guesser
+     * @return FormTypeGuesserInterface|null
      */
     protected function loadTypeGuesser()
     {

src/Symfony/Component/Form/AbstractRendererEngine.php

@@ -133,7 +133,7 @@ abstract protected function loadResourceForBlockName($cacheKey, FormView $view,
      *                                     resource
      * @param FormView $view               The form view for finding the applying
      *                                     themes
-     * @param array    $blockNameHierarchy The block hierarchy, with the most
+     * @param string[] $blockNameHierarchy The block hierarchy, with the most
      *                                     specific block name at the end
      * @param int      $hierarchyLevel     The level in the block hierarchy that
      *                                     should be loaded

src/Symfony/Component/Form/Button.php

@@ -22,7 +22,7 @@
 class Button implements \IteratorAggregate, FormInterface
 {
     /**
-     * @var FormInterface|null
+     * @var FormInterface
      */
     private $parent;
 
@@ -111,6 +111,8 @@ public function setParent(FormInterface $parent = null)
         }
 
         $this->parent = $parent;
+
+        return $this;
     }
 
     /**
@@ -199,32 +201,37 @@ public function getErrors($deep = false, $flatten = true)
      * This method should not be invoked.
      *
      * @param mixed $modelData
+     *
+     * @return $this
      */
     public function setData($modelData)
     {
-        // called during initialization of the form tree
-        // noop
+        // no-op, called during initialization of the form tree
+        return $this;
     }
 
     /**
      * Unsupported method.
      */
     public function getData()
     {
+        return null;
     }
 
     /**
      * Unsupported method.
      */
     public function getNormData()
     {
+        return null;
     }
 
     /**
      * Unsupported method.
      */
     public function getViewData()
     {
+        return null;
     }
 
     /**
@@ -240,7 +247,7 @@ public function getExtraData()
     /**
      * Returns the button's configuration.
      *
-     * @return FormConfigInterface The configuration
+     * @return FormConfigInterface The configuration instance
      */
     public function getConfig()
     {
@@ -272,6 +279,7 @@ public function getName()
      */
     public function getPropertyPath()
     {
+        return null;
     }
 
     /**
@@ -309,11 +317,11 @@ public function isRequired()
      */
     public function isDisabled()
     {
-        if (null === $this->parent || !$this->parent->isDisabled()) {
-            return $this->config->getDisabled();
+        if ($this->parent && $this->parent->isDisabled()) {
+            return true;
         }
 
-        return true;
+        return $this->config->getDisabled();
     }
 
     /**
@@ -341,6 +349,7 @@ public function isSynchronized()
      */
     public function getTransformationFailure()
     {
+        return null;
     }
 
     /**
@@ -368,7 +377,7 @@ public function handleRequest($request = null)
     /**
      * Submits data to the button.
      *
-     * @param string|null $submittedData The data
+     * @param string|null $submittedData Not used
      * @param bool        $clearMissing  Not used
      *
      * @return $this

src/Symfony/Component/Form/ButtonBuilder.php

@@ -22,9 +22,6 @@
  */
 class ButtonBuilder implements \IteratorAggregate, FormBuilderInterface
 {
-    /**
-     * @var bool
-     */
     protected $locked = false;
 
     /**
@@ -53,8 +50,6 @@ class ButtonBuilder implements \IteratorAggregate, FormBuilderInterface
     private $options;
 
     /**
-     * Creates a new button builder.
-     *
      * @param string $name    The name of the button
      * @param array  $options The button's options
      *
@@ -524,6 +519,7 @@ public function getFormConfig()
      */
     public function getEventDispatcher()
     {
+        return null;
     }
 
     /**
@@ -539,6 +535,7 @@ public function getName()
      */
     public function getPropertyPath()
     {
+        return null;
     }
 
     /**
@@ -606,6 +603,7 @@ public function getModelTransformers()
      */
     public function getDataMapper()
     {
+        return null;
     }
 
     /**
@@ -643,6 +641,7 @@ public function getErrorBubbling()
      */
     public function getEmptyData()
     {
+        return null;
     }
 
     /**
@@ -685,13 +684,15 @@ public function getAttribute($name, $default = null)
      */
     public function getData()
     {
+        return null;
     }
 
     /**
      * Unsupported method.
      */
     public function getDataClass()
     {
+        return null;
     }
 
     /**
@@ -709,27 +710,31 @@ public function getDataLocked()
      */
     public function getFormFactory()
     {
+        throw new BadMethodCallException('Buttons do not support adding children.');
     }
 
     /**
      * Unsupported method.
      */
     public function getAction()
     {
+        return null;
     }
 
     /**
      * Unsupported method.
      */
     public function getMethod()
     {
+        return null;
     }
 
     /**
      * Unsupported method.
      */
     public function getRequestHandler()
     {
+        return null;
     }
 
     /**

src/Symfony/Component/Form/CallbackTransformer.php

@@ -11,9 +11,6 @@
 
 namespace Symfony\Component\Form;
 
-use Symfony\Component\Form\Exception\TransformationFailedException;
-use Symfony\Component\Form\Exception\UnexpectedTypeException;
-
 class CallbackTransformer implements DataTransformerInterface
 {
     private $transform;
@@ -30,30 +27,15 @@ public function __construct(callable $transform, callable $reverseTransform)
     }
 
     /**
-     * Transforms a value from the original representation to a transformed representation.
-     *
-     * @param mixed $data The value in the original representation
-     *
-     * @return mixed The value in the transformed representation
-     *
-     * @throws UnexpectedTypeException       when the argument is not of the expected type
-     * @throws TransformationFailedException when the transformation fails
+     * {@inheritdoc}
      */
     public function transform($data)
     {
         return \call_user_func($this->transform, $data);
     }
 
     /**
-     * Transforms a value from the transformed representation to its original
-     * representation.
-     *
-     * @param mixed $data The value in the transformed representation
-     *
-     * @return mixed The value in the original representation
-     *
-     * @throws UnexpectedTypeException       when the argument is not of the expected type
-     * @throws TransformationFailedException when the transformation fails
+     * {@inheritdoc}
      */
     public function reverseTransform($data)
     {

src/Symfony/Component/Form/DataMapperInterface.php

@@ -17,22 +17,46 @@
 interface DataMapperInterface
 {
     /**
-     * Maps properties of some data to a list of forms.
+     * Maps the view data of a compound form to its children.
      *
-     * @param mixed                        $data  Structured data
-     * @param FormInterface[]|\Traversable $forms A list of {@link FormInterface} instances
+     * The method is responsible for calling {@link FormInterface::setData()}
+     * on the children of compound forms, defining their underlying model data.
+     *
+     * @param mixed                        $viewData View data of the compound form being initialized
+     * @param FormInterface[]|\Traversable $forms    A list of {@link FormInterface} instances
      *
      * @throws Exception\UnexpectedTypeException if the type of the data parameter is not supported
      */
-    public function mapDataToForms($data, $forms);
+    public function mapDataToForms($viewData, $forms);
 
     /**
-     * Maps the data of a list of forms into the properties of some data.
+     * Maps the model data of a list of children forms into the view data of their parent.
+     *
+     * This is the internal cascade call of FormInterface::submit for compound forms, since they
+     * cannot be bound to any input nor the request as scalar, but their children may:
+     *
+     *     $compoundForm->submit($arrayOfChildrenViewData)
+     *     // inside:
+     *     $childForm->submit($childViewData);
+     *     // for each entry, do the same and/or reverse transform
+     *     $this->dataMapper->mapFormsToData($compoundForm, $compoundInitialViewData)
+     *     // then reverse transform
+     *
+     * When a simple form is submitted the following is happening:
+     *
+     *     $simpleForm->submit($submittedViewData)
+     *     // inside:
+     *     $this->viewData = $submittedViewData
+     *     // then reverse transform
+     *
+     * The model data can be an array or an object, so this second argument is always passed
+     * by reference.
      *
-     * @param FormInterface[]|\Traversable $forms A list of {@link FormInterface} instances
-     * @param mixed                        $data  Structured data
+     * @param FormInterface[]|\Traversable $forms    A list of {@link FormInterface} instances
+     * @param mixed                        $viewData The compound form's view data that get mapped
+     *                                               its children model data
      *
      * @throws Exception\UnexpectedTypeException if the type of the data parameter is not supported
      */
-    public function mapFormsToData($forms, &$data);
+    public function mapFormsToData($forms, &$viewData);
 }

src/Symfony/Component/Form/DataTransformerInterface.php

@@ -23,23 +23,35 @@ interface DataTransformerInterface
     /**
      * Transforms a value from the original representation to a transformed representation.
      *
-     * This method is called on two occasions inside a form field:
+     * This method is called when the form field is initialized with its default data, on
+     * two occasions for two types of transformers:
      *
-     * 1. When the form field is initialized with the data attached from the datasource (object or array).
-     * 2. When data from a request is submitted using {@link Form::submit()} to transform the new input data
-     *    back into the renderable format. For example if you have a date field and submit '2009-10-10'
-     *    you might accept this value because its easily parsed, but the transformer still writes back
-     *    "2009/10/10" onto the form field (for further displaying or other purposes).
+     * 1. Model transformers which normalize the model data.
+     *    This is mainly useful when the same form type (the same configuration)
+     *    has to handle different kind of underlying data, e.g The DateType can
+     *    deal with strings or \DateTime objects as input.
+     *
+     * 2. View transformers which adapt the normalized data to the view format.
+     *    a/ When the form is simple, the value returned by convention is used
+     *       directly in the view and thus can only be a string or an array. In
+     *       this case the data class should be null.
+     *
+     *    b/ When the form is compound the returned value should be an array or
+     *       an object to be mapped to the children. Each property of the compound
+     *       data will be used as model data by each child and will be transformed
+     *       too. In this case data class should be the class of the object, or null
+     *       when it is an array.
+     *
+     * All transformers are called in a configured order from model data to view value.
+     * At the end of this chain the view data will be validated against the data class
+     * setting.
      *
      * This method must be able to deal with empty values. Usually this will
      * be NULL, but depending on your implementation other empty values are
      * possible as well (such as empty strings). The reasoning behind this is
-     * that value transformers must be chainable. If the transform() method
-     * of the first value transformer outputs NULL, the second value transformer
-     * must be able to process that value.
-     *
-     * By convention, transform() should return an empty string if NULL is
-     * passed.
+     * that data transformers must be chainable. If the transform() method
+     * of the first data transformer outputs NULL, the second must be able to
+     * process that value.
      *
      * @param mixed $value The value in the original representation
      *
@@ -54,7 +66,10 @@ public function transform($value);
      * representation.
      *
      * This method is called when {@link Form::submit()} is called to transform the requests tainted data
-     * into an acceptable format for your data processing/model layer.
+     * into an acceptable format.
+     *
+     * The same transformers are called in the reverse order so the responsibility is to
+     * return one of the types that would be expected as input of transform().
      *
      * This method must be able to deal with empty values. Usually this will
      * be an empty string, but depending on your implementation other empty