<?php

/*

 * This file is part of the Symfony package.

 *

 * (c) Fabien Potencier <fabien@symfony.com>

 *

 * For the full copyright and license information, please view the LICENSE

 * file that was distributed with this source code.

 */

namespace Symfony\Component\Form;

use Symfony\Component\Form\Event\DataEvent;

use Symfony\Component\Form\Event\FilterDataEvent;

use Symfony\Component\Form\Exception\FormException;

use Symfony\Component\Form\Exception\UnexpectedTypeException;

use Symfony\Component\Form\Exception\TransformationFailedException;

use Symfony\Component\HttpFoundation\Request;

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:

 *

 *   (1) the format required by the form's object

 *   (2) a normalized format for internal processing

 *   (3) the 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

 * to a DateTime object (2). In the HTML representation of your form, a

 * 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

 * 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().

 *

 * 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.

 *

 * @author Fabien Potencier <fabien@symfony.com>

 * @author Bernhard Schussek <bernhard.schussek@symfony.com>

 */

class Form implements \IteratorAggregate, FormInterface

{

    /**

     * The name of this form

     * @var string

     */

    private $name;

    /**

     * The parent of this form

     * @var FormInterface

     */

    private $parent;

    /**

     * The children of this form

     * @var array An array of FormInterface instances

     */

    private $children = array();

    /**

     * The mapper for mapping data to children and back

     * @var DataMapper\DataMapperInterface

     */

    private $dataMapper;

    /**

     * The errors of this form

     * @var array An array of FromError instances

     */

    private $errors = array();

    /**

     * Whether added errors should bubble up to the parent

     * @var Boolean

     */

    private $errorBubbling;

    /**

     * Whether this form is bound

     * @var Boolean

     */

    private $bound = false;

    /**

     * Whether this form may not be empty

     * @var Boolean

     */

    private $required;

    /**

     * The form data in application format

     * @var mixed

     */

    private $appData;

    /**

     * The form data in normalized format

     * @var mixed

     */

    private $normData;

    /**

     * The form data in client format

     * @var mixed

     */

    private $clientData;

    /**

     * Data used for the client data when no value is bound

     * @var mixed

     */

    private $emptyData = '';

    /**

     * The bound values that don't belong to any children

     * @var array

     */

    private $extraData = array();

    /**

     * The transformers for transforming from application to normalized format

     * and back

     * @var array An array of DataTransformerInterface

     */

    private $normTransformers;

    /**

     * The transformers for transforming from normalized to client format and

     * back

     * @var array An array of DataTransformerInterface

     */

    private $clientTransformers;

    /**

     * Whether the data in application, normalized and client format is

     * synchronized. Data may not be synchronized if transformation errors

     * occur.

     * @var Boolean

     */

    private $synchronized = true;

    /**

     * The validators attached to this form

     * @var array An array of FormValidatorInterface instances

     */

    private $validators;

    /**

     * Whether this form may only be read, but not bound

     * @var Boolean

     */

    private $readOnly = false;

    /**

     * The dispatcher for distributing events of this form

     * @var Symfony\Component\EventDispatcher\EventDispatcherInterface

     */

    private $dispatcher;

    /**

     * Key-value store for arbitrary attributes attached to this form

     * @var array

     */

    private $attributes;

    /**

     * The FormTypeInterface instances used to create this form

     * @var array An array of FormTypeInterface

     */

    private $types;

    public function __construct($name, EventDispatcherInterface $dispatcher,

        array $types = array(), array $clientTransformers = array(),

        array $normTransformers = array(),

        DataMapperInterface $dataMapper = null, array $validators = array(),

        $required = false, $readOnly = false, $errorBubbling = false,

        $emptyData = null, array $attributes = array())

    {

        foreach ($clientTransformers as $transformer) {

            if (!$transformer instanceof DataTransformerInterface) {

                throw new UnexpectedTypeException($transformer, 'Symfony\Component\Form\DataTransformerInterface');

            }

        }

        foreach ($normTransformers as $transformer) {

            if (!$transformer instanceof DataTransformerInterface) {

                throw new UnexpectedTypeException($transformer, 'Symfony\Component\Form\DataTransformerInterface');

            }

        }

        foreach ($validators as $validator) {

            if (!$validator instanceof FormValidatorInterface) {

                throw new UnexpectedTypeException($validator, 'Symfony\Component\Form\FormValidatorInterface');

            }

        }

        $this->name = (string) $name;

        $this->dispatcher = $dispatcher;

        $this->types = $types;

        $this->clientTransformers = $clientTransformers;

        $this->normTransformers = $normTransformers;

        $this->dataMapper = $dataMapper;

        $this->validators = $validators;

        $this->required = (Boolean) $required;

        $this->readOnly = (Boolean) $readOnly;

        $this->errorBubbling = (Boolean) $errorBubbling;

        $this->emptyData = $emptyData;

        $this->attributes = $attributes;

        $this->setData(null);

    }

    public function __clone()

    {

        foreach ($this->children as $key => $child) {

            $this->children[$key] = clone $child;

        }

    }

    /**

     * Returns the name by which the form is identified in forms.

     *

     * @return string  The name of the form.

     */

    public function getName()

    {

        return $this->name;

    }

    /**

     * Returns the types used by this form.

     *

     * @return array An array of FormTypeInterface

     */

    public function getTypes()

    {

        return $this->types;

    }

    /**

     * Returns whether the form is required to be filled out.

     *

     * If the form has a parent and the parent is not required, this method

     * will always return false. Otherwise the value set with setRequired()

     * is returned.

     *

     * @return Boolean

     */

    public function isRequired()

    {

        if (null === $this->parent || $this->parent->isRequired()) {

            return $this->required;

        }

        return false;

    }

    /**

     * Returns whether this form is read only.

     *

     * The content of a read-only form is displayed, but not allowed to be

     * modified. The validation of modified read-only forms should fail.

     *

     * Fields whose parents are read-only are considered read-only regardless of

     * their own state.

     *

     * @return Boolean

     */

    public function isReadOnly()

    {

        if (null === $this->parent || !$this->parent->isReadOnly()) {

            return $this->readOnly;

        }

        return true;

    }

    /**

     * Sets the parent form.

     *

     * @param FormInterface $parent The parent form

     *

     * @return Form The current form

     */

    public function setParent(FormInterface $parent = null)

    {

        $this->parent = $parent;

        return $this;

    }

    /**

     * Returns the parent field.

     *

     * @return FormInterface The parent field

     */

    public function getParent()

    {

        return $this->parent;

    }

    /**

     * Returns whether the form has a parent.

     *

     * @return Boolean

     */

    public function hasParent()

    {

        return null !== $this->parent;

    }

    /**

     * Returns the root of the form tree.

     *

     * @return FormInterface  The root of the tree

     */

    public function getRoot()

    {

        return $this->parent ? $this->parent->getRoot() : $this;

    }

    /**

     * Returns whether the field is the root of the form tree.

     *

     * @return Boolean

     */

    public function isRoot()

    {

        return !$this->hasParent();

    }

    /**

     * Returns whether the form has an attribute with the given name.

     *

     * @param string $name The name of the attribute

     *

     * @return Boolean

     */

    public function hasAttribute($name)

    {

        return isset($this->attributes[$name]);

    }

    /**

     * Returns the value of the attributes with the given name.

     *

     * @param string $name The name of the attribute

     */

    public function getAttribute($name)

    {

        return $this->attributes[$name];

    }

    /**

     * Updates the field with default data.

     *

     * @param array $appData The data formatted as expected for the underlying object

     *

     * @return Form The current form

     */

    public function setData($appData)

    {

        $event = new DataEvent($this, $appData);

        $this->dispatcher->dispatch(FormEvents::PRE_SET_DATA, $event);

        // Hook to change content of the data

        $event = new FilterDataEvent($this, $appData);

        $this->dispatcher->dispatch(FormEvents::SET_DATA, $event);

        $appData = $event->getData();

        // Treat data as strings unless a value transformer exists

        if (!$this->clientTransformers && !$this->normTransformers && is_scalar($appData)) {

            $appData = (string) $appData;

        }

        // Synchronize representations - must not change the content!

        $normData = $this->appToNorm($appData);

        $clientData = $this->normToClient($normData);

        $this->appData = $appData;

        $this->normData = $normData;

        $this->clientData = $clientData;

        $this->synchronized = true;

        if ($this->dataMapper) {

            // Update child forms from the data

            $this->dataMapper->mapDataToForms($clientData, $this->children);

        }

        $event = new DataEvent($this, $appData);

        $this->dispatcher->dispatch(FormEvents::POST_SET_DATA, $event);

        return $this;

    }

    /**

     * Returns the data in the format needed for the underlying object.

     *

     * @return mixed

     */

    public function getData()

    {

        return $this->appData;

    }

    /**

     * Returns the data transformed by the value transformer.

     *

     * @return string

     */

    public function getClientData()

    {

        return $this->clientData;

    }

    /**

     * Returns the extra data.

     *

     * @return array The bound data which do not belong to a child

     */

    public function getExtraData()

    {

        return $this->extraData;

    }

    /**

     * Binds data to the field, transforms and validates it.

     *

     * @param string|array $clientData The data

     *

     * @return Form The current form

     *

     * @throws UnexpectedTypeException

     */

    public function bind($clientData)

    {

        if ($this->readOnly) {

            $this->bound = true;

            return $this;

        }

        if (is_scalar($clientData) || null === $clientData) {