vendor/symfony/form/Form.php line 643

Open in your IDE?
  1. <?php
  3. /*
  4.  * This file is part of the Symfony package.
  5.  *
  6.  * (c) Fabien Potencier <fabien@symfony.com>
  7.  *
  8.  * For the full copyright and license information, please view the LICENSE
  9.  * file that was distributed with this source code.
  10.  */
  12. namespace Symfony\Component\Form;
  14. use Symfony\Component\EventDispatcher\LegacyEventDispatcherProxy;
  15. use Symfony\Component\Form\Event\PostSetDataEvent;
  16. use Symfony\Component\Form\Event\PostSubmitEvent;
  17. use Symfony\Component\Form\Event\PreSetDataEvent;
  18. use Symfony\Component\Form\Event\PreSubmitEvent;
  19. use Symfony\Component\Form\Event\SubmitEvent;
  20. use Symfony\Component\Form\Exception\AlreadySubmittedException;
  21. use Symfony\Component\Form\Exception\LogicException;
  22. use Symfony\Component\Form\Exception\OutOfBoundsException;
  23. use Symfony\Component\Form\Exception\RuntimeException;
  24. use Symfony\Component\Form\Exception\TransformationFailedException;
  25. use Symfony\Component\Form\Exception\UnexpectedTypeException;
  26. use Symfony\Component\Form\Extension\Core\Type\TextType;
  27. use Symfony\Component\Form\Util\FormUtil;
  28. use Symfony\Component\Form\Util\InheritDataAwareIterator;
  29. use Symfony\Component\Form\Util\OrderedHashMap;
  30. use Symfony\Component\PropertyAccess\PropertyPath;
  31. use Symfony\Component\PropertyAccess\PropertyPathInterface;
  33. /**
  34.  * Form represents a form.
  35.  *
  36.  * To implement your own form fields, you need to have a thorough understanding
  37.  * of the data flow within a form. A form stores its data in three different
  38.  * representations:
  39.  *
  40.  *   (1) the "model" format required by the form's object
  41.  *   (2) the "normalized" format for internal processing
  42.  *   (3) the "view" format used for display simple fields
  43.  *       or map children model data for compound fields
  44.  *
  45.  * A date field, for example, may store a date as "Y-m-d" string (1) in the
  46.  * object. To facilitate processing in the field, this value is normalized
  47.  * to a DateTime object (2). In the HTML representation of your form, a
  48.  * localized string (3) may be presented to and modified by the user, or it could be an array of values
  49.  * to be mapped to choices fields.
  50.  *
  51.  * In most cases, format (1) and format (2) will be the same. For example,
  52.  * a checkbox field uses a Boolean value for both internal processing and
  53.  * storage in the object. In these cases you need to set a view transformer
  54.  * to convert between formats (2) and (3). You can do this by calling
  55.  * addViewTransformer().
  56.  *
  57.  * In some cases though it makes sense to make format (1) configurable. To
  58.  * demonstrate this, let's extend our above date field to store the value
  59.  * either as "Y-m-d" string or as timestamp. Internally we still want to
  60.  * use a DateTime object for processing. To convert the data from string/integer
  61.  * to DateTime you can set a model transformer by calling
  62.  * addModelTransformer(). The normalized data is then converted to the displayed
  63.  * data as described before.
  64.  *
  65.  * The conversions (1) -> (2) -> (3) use the transform methods of the transformers.
  66.  * The conversions (3) -> (2) -> (1) use the reverseTransform methods of the transformers.
  67.  *
  68.  * @author Fabien Potencier <fabien@symfony.com>
  69.  * @author Bernhard Schussek <bschussek@gmail.com>
  70.  */
  71. class Form implements \IteratorAggregate, FormInterface, ClearableErrorsInterface
  72. {
  73.     /**
  74.      * @var FormConfigInterface
  75.      */
  76.     private $config;
  78.     /**
  79.      * @var FormInterface|null
  80.      */
  81.     private $parent;
  83.     /**
  84.      * A map of FormInterface instances.
  85.      *
  86.      * @var FormInterface[]|OrderedHashMap
  87.      */
  88.     private $children;
  90.     /**
  91.      * @var FormError[]
  92.      */
  93.     private $errors = [];
  95.     /**
  96.      * @var bool
  97.      */
  98.     private $submitted = false;
  100.     /**
  101.      * The button that was used to submit the form.
  102.      *
  103.      * @var FormInterface|ClickableInterface|null
  104.      */
  105.     private $clickedButton;
  107.     /**
  108.      * @var mixed
  109.      */
  110.     private $modelData;
  112.     /**
  113.      * @var mixed
  114.      */
  115.     private $normData;
  117.     /**
  118.      * @var mixed
  119.      */
  120.     private $viewData;
  122.     /**
  123.      * The submitted values that don't belong to any children.
  124.      *
  125.      * @var array
  126.      */
  127.     private $extraData = [];
  129.     /**
  130.      * The transformation failure generated during submission, if any.
  131.      *
  132.      * @var TransformationFailedException|null
  133.      */
  134.     private $transformationFailure;
  136.     /**
  137.      * Whether the form's data has been initialized.
  138.      *
  139.      * When the data is initialized with its default value, that default value
  140.      * is passed through the transformer chain in order to synchronize the
  141.      * model, normalized and view format for the first time. This is done
  142.      * lazily in order to save performance when {@link setData()} is called
  143.      * manually, making the initialization with the configured default value
  144.      * superfluous.
  145.      *
  146.      * @var bool
  147.      */
  148.     private $defaultDataSet = false;
  150.     /**
  151.      * Whether setData() is currently being called.
  152.      *
  153.      * @var bool
  154.      */
  155.     private $lockSetData = false;
  157.     /**
  158.      * @var string
  159.      */
  160.     private $name = '';
  162.     /**
  163.      * Whether the form inherits its underlying data from its parent.
  164.      *
  165.      * @var bool
  166.      */
  167.     private $inheritData;
  169.     /**
  170.      * @var PropertyPathInterface|null
  171.      */
  172.     private $propertyPath;
  174.     /**
  175.      * @throws LogicException if a data mapper is not provided for a compound form
  176.      */
  177.     public function __construct(FormConfigInterface $config)
  178.     {
  179.         // Compound forms always need a data mapper, otherwise calls to
  180.         // `setData` and `add` will not lead to the correct population of
  181.         // the child forms.
  182.         if ($config->getCompound() && !$config->getDataMapper()) {
  183.             throw new LogicException('Compound forms need a data mapper.');
  184.         }
  186.         // If the form inherits the data from its parent, it is not necessary
  187.         // to call setData() with the default data.
  188.         if ($this->inheritData = $config->getInheritData()) {
  189.             $this->defaultDataSet = true;
  190.         }
  192.         $this->config = $config;
  193.         $this->children = new OrderedHashMap();
  194.         $this->name = $config->getName();
  195.     }
  197.     public function __clone()
  198.     {
  199.         $this->children = clone $this->children;
  201.         foreach ($this->children as $key => $child) {
  202.             $this->children[$key] = clone $child;
  203.         }
  204.     }
  206.     /**
  207.      * {@inheritdoc}
  208.      */
  209.     public function getConfig()
  210.     {
  211.         return $this->config;
  212.     }
  214.     /**
  215.      * {@inheritdoc}
  216.      */
  217.     public function getName()
  218.     {
  219.         return $this->name;
  220.     }
  222.     /**
  223.      * {@inheritdoc}
  224.      */
  225.     public function getPropertyPath()
  226.     {
  227.         if ($this->propertyPath || $this->propertyPath = $this->config->getPropertyPath()) {
  228.             return $this->propertyPath;
  229.         }
  231.         if ('' === $this->name) {
  232.             return null;
  233.         }
  235.         $parent = $this->parent;
  237.         while ($parent && $parent->getConfig()->getInheritData()) {
  238.             $parent = $parent->getParent();
  239.         }
  241.         if ($parent && null === $parent->getConfig()->getDataClass()) {
  242.             $this->propertyPath = new PropertyPath('['.$this->name.']');
  243.         } else {
  244.             $this->propertyPath = new PropertyPath($this->name);
  245.         }
  247.         return $this->propertyPath;
  248.     }
  250.     /**
  251.      * {@inheritdoc}
  252.      */
  253.     public function isRequired()
  254.     {
  255.         if (null === $this->parent || $this->parent->isRequired()) {
  256.             return $this->config->getRequired();
  257.         }
  259.         return false;
  260.     }
  262.     /**
  263.      * {@inheritdoc}
  264.      */
  265.     public function isDisabled()
  266.     {
  267.         if (null === $this->parent || !$this->parent->isDisabled()) {
  268.             return $this->config->getDisabled();
  269.         }
  271.         return true;
  272.     }
  274.     /**
  275.      * {@inheritdoc}
  276.      */
  277.     public function setParent(FormInterface $parent = null)
  278.     {
  279.         if ($this->submitted) {
  280.             throw new AlreadySubmittedException('You cannot set the parent of a submitted form.');
  281.         }
  283.         if (null !== $parent && '' === $this->name) {
  284.             throw new LogicException('A form with an empty name cannot have a parent form.');
  285.         }
  287.         $this->parent = $parent;
  289.         return $this;
  290.     }
  292.     /**
  293.      * {@inheritdoc}
  294.      */
  295.     public function getParent()
  296.     {
  297.         return $this->parent;
  298.     }
  300.     /**
  301.      * {@inheritdoc}
  302.      */
  303.     public function getRoot()
  304.     {
  305.         return $this->parent ? $this->parent->getRoot() : $this;
  306.     }
  308.     /**
  309.      * {@inheritdoc}
  310.      */
  311.     public function isRoot()
  312.     {
  313.         return null === $this->parent;
  314.     }
  316.     /**
  317.      * {@inheritdoc}
  318.      */
  319.     public function setData($modelData)
  320.     {
  321.         // If the form is submitted while disabled, it is set to submitted, but the data is not
  322.         // changed. In such cases (i.e. when the form is not initialized yet) don't
  323.         // abort this method.
  324.         if ($this->submitted && $this->defaultDataSet) {
  325.             throw new AlreadySubmittedException('You cannot change the data of a submitted form.');
  326.         }
  328.         // If the form inherits its parent's data, disallow data setting to
  329.         // prevent merge conflicts
  330.         if ($this->inheritData) {
  331.             throw new RuntimeException('You cannot change the data of a form inheriting its parent data.');
  332.         }
  334.         // Don't allow modifications of the configured data if the data is locked
  335.         if ($this->config->getDataLocked() && $modelData !== $this->config->getData()) {
  336.             return $this;
  337.         }
  339.         if (\is_object($modelData) && !$this->config->getByReference()) {
  340.             $modelData = clone $modelData;
  341.         }
  343.         if ($this->lockSetData) {
  344.             throw new RuntimeException('A cycle was detected. Listeners to the PRE_SET_DATA event must not call setData(). You should call setData() on the FormEvent object instead.');
  345.         }
  347.         $this->lockSetData = true;
  348.         $dispatcher = LegacyEventDispatcherProxy::decorate($this->config->getEventDispatcher());
  350.         // Hook to change content of the model data before transformation and mapping children
  351.         if ($dispatcher->hasListeners(FormEvents::PRE_SET_DATA)) {
  352.             $event = new PreSetDataEvent($this, $modelData);
  353.             $dispatcher->dispatch($event, FormEvents::PRE_SET_DATA);
  354.             $modelData = $event->getData();
  355.         }
  357.         // Treat data as strings unless a transformer exists
  358.         if (is_scalar($modelData) && !$this->config->getViewTransformers() && !$this->config->getModelTransformers()) {
  359.             $modelData = (string) $modelData;
  360.         }
  362.         // Synchronize representations - must not change the content!
  363.         // Transformation exceptions are not caught on initialization
  364.         $normData = $this->modelToNorm($modelData);
  365.         $viewData = $this->normToView($normData);
  367.         // Validate if view data matches data class (unless empty)
  368.         if (!FormUtil::isEmpty($viewData)) {
  369.             $dataClass = $this->config->getDataClass();
  371.             if (null !== $dataClass && !$viewData instanceof $dataClass) {
  372.                 $actualType = \is_object($viewData)
  373.                     ? 'an instance of class '.\get_class($viewData)
  374.                     : 'a(n) '.\gettype($viewData);
  376.                 throw new LogicException('The form\'s view data is expected to be an instance of class '.$dataClass.', but is '.$actualType.'. You can avoid this error by setting the "data_class" option to null or by adding a view transformer that transforms '.$actualType.' to an instance of '.$dataClass.'.');
  377.             }
  378.         }
  380.         $this->modelData = $modelData;
  381.         $this->normData = $normData;
  382.         $this->viewData = $viewData;
  383.         $this->defaultDataSet = true;
  384.         $this->lockSetData = false;
  386.         // Compound forms don't need to invoke this method if they don't have children
  387.         if (\count($this->children) > 0) {
  388.             // Update child forms from the data (unless their config data is locked)
  389.             $this->config->getDataMapper()->mapDataToForms($viewData, new \RecursiveIteratorIterator(new InheritDataAwareIterator($this->children)));
  390.         }
  392.         if ($dispatcher->hasListeners(FormEvents::POST_SET_DATA)) {
  393.             $event = new PostSetDataEvent($this, $modelData);
  394.             $dispatcher->dispatch($event, FormEvents::POST_SET_DATA);
  395.         }
  397.         return $this;
  398.     }
  400.     /**
  401.      * {@inheritdoc}
  402.      */
  403.     public function getData()
  404.     {
  405.         if ($this->inheritData) {
  406.             if (!$this->parent) {
  407.                 throw new RuntimeException('The form is configured to inherit its parent\'s data, but does not have a parent.');
  408.             }
  410.             return $this->parent->getData();
  411.         }
  413.         if (!$this->defaultDataSet) {
  414.             if ($this->lockSetData) {
  415.                 throw new RuntimeException('A cycle was detected. Listeners to the PRE_SET_DATA event must not call getData() if the form data has not already been set. You should call getData() on the FormEvent object instead.');
  416.             }
  418.             $this->setData($this->config->getData());
  419.         }
  421.         return $this->modelData;
  422.     }
  424.     /**
  425.      * {@inheritdoc}
  426.      */
  427.     public function getNormData()
  428.     {
  429.         if ($this->inheritData) {
  430.             if (!$this->parent) {
  431.                 throw new RuntimeException('The form is configured to inherit its parent\'s data, but does not have a parent.');
  432.             }
  434.             return $this->parent->getNormData();
  435.         }
  437.         if (!$this->defaultDataSet) {
  438.             if ($this->lockSetData) {
  439.                 throw new RuntimeException('A cycle was detected. Listeners to the PRE_SET_DATA event must not call getNormData() if the form data has not already been set.');
  440.             }
  442.             $this->setData($this->config->getData());
  443.         }
  445.         return $this->normData;
  446.     }
  448.     /**
  449.      * {@inheritdoc}
  450.      */
  451.     public function getViewData()
  452.     {
  453.         if ($this->inheritData) {
  454.             if (!$this->parent) {
  455.                 throw new RuntimeException('The form is configured to inherit its parent\'s data, but does not have a parent.');
  456.             }
  458.             return $this->parent->getViewData();
  459.         }
  461.         if (!$this->defaultDataSet) {
  462.             if ($this->lockSetData) {
  463.                 throw new RuntimeException('A cycle was detected. Listeners to the PRE_SET_DATA event must not call getViewData() if the form data has not already been set.');
  464.             }
  466.             $this->setData($this->config->getData());
  467.         }
  469.         return $this->viewData;
  470.     }
  472.     /**
  473.      * {@inheritdoc}
  474.      */
  475.     public function getExtraData()
  476.     {
  477.         return $this->extraData;
  478.     }
  480.     /**
  481.      * {@inheritdoc}
  482.      */
  483.     public function initialize()
  484.     {
  485.         if (null !== $this->parent) {
  486.             throw new RuntimeException('Only root forms should be initialized.');
  487.         }
  489.         // Guarantee that the *_SET_DATA events have been triggered once the
  490.         // form is initialized. This makes sure that dynamically added or
  491.         // removed fields are already visible after initialization.
  492.         if (!$this->defaultDataSet) {
  493.             $this->setData($this->config->getData());
  494.         }
  496.         return $this;
  497.     }
  499.     /**
  500.      * {@inheritdoc}
  501.      */
  502.     public function handleRequest($request = null)
  503.     {
  504.         $this->config->getRequestHandler()->handleRequest($this, $request);
  506.         return $this;
  507.     }
  509.     /**
  510.      * {@inheritdoc}
  511.      */
  512.     public function submit($submittedData, $clearMissing = true)
  513.     {
  514.         if ($this->submitted) {
  515.             throw new AlreadySubmittedException('A form can only be submitted once.');
  516.         }
  518.         // Initialize errors in the very beginning so we're sure
  519.         // they are collectable during submission only
  520.         $this->errors = [];
  522.         // Obviously, a disabled form should not change its data upon submission.
  523.         if ($this->isDisabled()) {
  524.             $this->submitted = true;
  526.             return $this;
  527.         }
  529.         // The data must be initialized if it was not initialized yet.
  530.         // This is necessary to guarantee that the *_SET_DATA listeners
  531.         // are always invoked before submit() takes place.
  532.         if (!$this->defaultDataSet) {
  533.             $this->setData($this->config->getData());
  534.         }
  536.         // Treat false as NULL to support binding false to checkboxes.
  537.         // Don't convert NULL to a string here in order to determine later
  538.         // whether an empty value has been submitted or whether no value has
  539.         // been submitted at all. This is important for processing checkboxes
  540.         // and radio buttons with empty values.
  541.         if (false === $submittedData) {
  542.             $submittedData = null;
  543.         } elseif (is_scalar($submittedData)) {
  544.             $submittedData = (string) $submittedData;
  545.         } elseif ($this->config->getRequestHandler()->isFileUpload($submittedData)) {
  546.             if (!$this->config->getOption('allow_file_upload')) {
  547.                 $submittedData = null;
  548.                 $this->transformationFailure = new TransformationFailedException('Submitted data was expected to be text or number, file upload given.');
  549.             }
  550.         } elseif (\is_array($submittedData) && !$this->config->getCompound() && !$this->config->hasOption('multiple')) {
  551.             $submittedData = null;
  552.             $this->transformationFailure = new TransformationFailedException('Submitted data was expected to be text or number, array given.');
  553.         }
  555.         $dispatcher = LegacyEventDispatcherProxy::decorate($this->config->getEventDispatcher());
  557.         $modelData = null;
  558.         $normData = null;
  559.         $viewData = null;
  561.         try {
  562.             if (null !== $this->transformationFailure) {
  563.                 throw $this->transformationFailure;
  564.             }
  566.             // Hook to change content of the data submitted by the browser
  567.             if ($dispatcher->hasListeners(FormEvents::PRE_SUBMIT)) {
  568.                 $event = new PreSubmitEvent($this, $submittedData);
  569.                 $dispatcher->dispatch($event, FormEvents::PRE_SUBMIT);
  570.                 $submittedData = $event->getData();
  571.             }
  573.             // Check whether the form is compound.
  574.             // This check is preferable over checking the number of children,
  575.             // since forms without children may also be compound.
  576.             // (think of empty collection forms)
  577.             if ($this->config->getCompound()) {
  578.                 if (null === $submittedData) {
  579.                     $submittedData = [];
  580.                 }
  582.                 if (!\is_array($submittedData)) {
  583.                     throw new TransformationFailedException('Compound forms expect an array or NULL on submission.');
  584.                 }
  586.                 foreach ($this->children as $name => $child) {
  587.                     $isSubmitted = \array_key_exists($name, $submittedData);
  589.                     if ($isSubmitted || $clearMissing) {
  590.                         $child->submit($isSubmitted ? $submittedData[$name] : null, $clearMissing);
  591.                         unset($submittedData[$name]);
  593.                         if (null !== $this->clickedButton) {
  594.                             continue;
  595.                         }
  597.                         if ($child instanceof ClickableInterface && $child->isClicked()) {
  598.                             $this->clickedButton = $child;
  600.                             continue;
  601.                         }
  603.                         if (method_exists($child, 'getClickedButton') && null !== $child->getClickedButton()) {
  604.                             $this->clickedButton = $child->getClickedButton();
  605.                         }
  606.                     }
  607.                 }
  609.                 $this->extraData = $submittedData;
  610.             }
  612.             // Forms that inherit their parents' data also are not processed,
  613.             // because then it would be too difficult to merge the changes in
  614.             // the child and the parent form. Instead, the parent form also takes
  615.             // changes in the grandchildren (i.e. children of the form that inherits
  616.             // its parent's data) into account.
  617.             // (see InheritDataAwareIterator below)
  618.             if (!$this->inheritData) {
  619.                 // If the form is compound, the view data is merged with the data
  620.                 // of the children using the data mapper.
  621.                 // If the form is not compound, the view data is assigned to the submitted data.
  622.                 $viewData = $this->config->getCompound() ? $this->viewData : $submittedData;
  624.                 if (FormUtil::isEmpty($viewData)) {
  625.                     $emptyData = $this->config->getEmptyData();
  627.                     if ($emptyData instanceof \Closure) {
  628.                         $emptyData = $emptyData($this, $viewData);
  629.                     }
  631.                     $viewData = $emptyData;
  632.                 }
  634.                 // Merge form data from children into existing view data
  635.                 // It is not necessary to invoke this method if the form has no children,
  636.                 // even if it is compound.
  637.                 if (\count($this->children) > 0) {
  638.                     // Use InheritDataAwareIterator to process children of
  639.                     // descendants that inherit this form's data.
  640.                     // These descendants will not be submitted normally (see the check
  641.                     // for $this->config->getInheritData() above)
  642.                     $this->config->getDataMapper()->mapFormsToData(
  643.                         new \RecursiveIteratorIterator(new InheritDataAwareIterator($this->children)),
  644.                         $viewData
  645.                     );
  646.                 }
  648.                 // Normalize data to unified representation
  649.                 $normData = $this->viewToNorm($viewData);
  651.                 // Hook to change content of the data in the normalized
  652.                 // representation
  653.                 if ($dispatcher->hasListeners(FormEvents::SUBMIT)) {
  654.                     $event = new SubmitEvent($this, $normData);
  655.                     $dispatcher->dispatch($event, FormEvents::SUBMIT);
  656.                     $normData = $event->getData();
  657.                 }
  659.                 // Synchronize representations - must not change the content!
  660.                 $modelData = $this->normToModel($normData);
  661.                 $viewData = $this->normToView($normData);
  662.             }
  663.         } catch (TransformationFailedException $e) {
  664.             $this->transformationFailure = $e;
  666.             // If $viewData was not yet set, set it to $submittedData so that
  667.             // the erroneous data is accessible on the form.
  668.             // Forms that inherit data never set any data, because the getters
  669.             // forward to the parent form's getters anyway.
  670.             if (null === $viewData && !$this->inheritData) {
  671.                 $viewData = $submittedData;
  672.             }
  673.         }
  675.         $this->submitted = true;
  676.         $this->modelData = $modelData;
  677.         $this->normData = $normData;
  678.         $this->viewData = $viewData;
  680.         if ($dispatcher->hasListeners(FormEvents::POST_SUBMIT)) {
  681.             $event = new PostSubmitEvent($this, $viewData);
  682.             $dispatcher->dispatch($event, FormEvents::POST_SUBMIT);
  683.         }
  685.         return $this;
  686.     }
  688.     /**
  689.      * {@inheritdoc}
  690.      */
  691.     public function addError(FormError $error)
  692.     {
  693.         if (null === $error->getOrigin()) {
  694.             $error->setOrigin($this);
  695.         }
  697.         if ($this->parent && $this->config->getErrorBubbling()) {
  698.             $this->parent->addError($error);
  699.         } else {
  700.             $this->errors[] = $error;
  701.         }
  703.         return $this;
  704.     }
  706.     /**
  707.      * {@inheritdoc}
  708.      */
  709.     public function isSubmitted()
  710.     {
  711.         return $this->submitted;
  712.     }
  714.     /**
  715.      * {@inheritdoc}
  716.      */
  717.     public function isSynchronized()
  718.     {
  719.         return null === $this->transformationFailure;
  720.     }
  722.     /**
  723.      * {@inheritdoc}
  724.      */
  725.     public function getTransformationFailure()
  726.     {
  727.         return $this->transformationFailure;
  728.     }
  730.     /**
  731.      * {@inheritdoc}
  732.      */
  733.     public function isEmpty()
  734.     {
  735.         foreach ($this->children as $child) {
  736.             if (!$child->isEmpty()) {
  737.                 return false;
  738.             }
  739.         }
  741.         return FormUtil::isEmpty($this->modelData) ||
  742.             // arrays, countables
  743.             ((\is_array($this->modelData) || $this->modelData instanceof \Countable) && 0 === \count($this->modelData)) ||
  744.             // traversables that are not countable
  745.             ($this->modelData instanceof \Traversable && 0 === iterator_count($this->modelData)) ||
  746.             // @internal - Do not rely on it, it will be removed in Symfony 5.1.
  747.             (false === $this->modelData && $this->config->getAttribute('_false_is_empty'));
  748.     }
  750.     /**
  751.      * {@inheritdoc}
  752.      */
  753.     public function isValid()
  754.     {
  755.         if (!$this->submitted) {
  756.             throw new LogicException('Cannot check if an unsubmitted form is valid. Call Form::isSubmitted() before Form::isValid().');
  757.         }
  759.         if ($this->isDisabled()) {
  760.             return true;
  761.         }
  763.         return 0 === \count($this->getErrors(true));
  764.     }
  766.     /**
  767.      * Returns the button that was used to submit the form.
  768.      *
  769.      * @return FormInterface|ClickableInterface|null
  770.      */
  771.     public function getClickedButton()
  772.     {
  773.         if ($this->clickedButton) {
  774.             return $this->clickedButton;
  775.         }
  777.         return $this->parent && method_exists($this->parent, 'getClickedButton') ? $this->parent->getClickedButton() : null;
  778.     }
  780.     /**
  781.      * {@inheritdoc}
  782.      */
  783.     public function getErrors($deep = false, $flatten = true)
  784.     {
  785.         $errors = $this->errors;
  787.         // Copy the errors of nested forms to the $errors array
  788.         if ($deep) {
  789.             foreach ($this as $child) {
  790.                 /** @var FormInterface $child */
  791.                 if ($child->isSubmitted() && $child->isValid()) {
  792.                     continue;
  793.                 }
  795.                 $iterator = $child->getErrors(true, $flatten);
  797.                 if (0 === \count($iterator)) {
  798.                     continue;
  799.                 }
  801.                 if ($flatten) {
  802.                     foreach ($iterator as $error) {
  803.                         $errors[] = $error;
  804.                     }
  805.                 } else {
  806.                     $errors[] = $iterator;
  807.                 }
  808.             }
  809.         }
  811.         return new FormErrorIterator($this, $errors);
  812.     }
  814.     /**
  815.      * {@inheritdoc}
  816.      *
  817.      * @return $this
  818.      */
  819.     public function clearErrors(bool $deep = false): self
  820.     {
  821.         $this->errors = [];
  823.         if ($deep) {
  824.             // Clear errors from children
  825.             foreach ($this as $child) {
  826.                 if ($child instanceof ClearableErrorsInterface) {
  827.                     $child->clearErrors(true);
  828.                 }
  829.             }
  830.         }
  832.         return $this;
  833.     }
  835.     /**
  836.      * {@inheritdoc}
  837.      */
  838.     public function all()
  839.     {
  840.         return iterator_to_array($this->children);
  841.     }
  843.     /**
  844.      * {@inheritdoc}
  845.      */
  846.     public function add($child, $type = null, array $options = [])
  847.     {
  848.         if ($this->submitted) {
  849.             throw new AlreadySubmittedException('You cannot add children to a submitted form.');
  850.         }
  852.         if (!$this->config->getCompound()) {
  853.             throw new LogicException('You cannot add children to a simple form. Maybe you should set the option "compound" to true?');
  854.         }
  856.         if (!$child instanceof FormInterface) {
  857.             if (!\is_string($child) && !\is_int($child)) {
  858.                 throw new UnexpectedTypeException($child, 'string or Symfony\Component\Form\FormInterface');
  859.             }
  861.             $child = (string) $child;
  863.             if (null !== $type && !\is_string($type)) {
  864.                 throw new UnexpectedTypeException($type, 'string or null');
  865.             }
  867.             // Never initialize child forms automatically
  868.             $options['auto_initialize'] = false;
  870.             if (null === $type && null === $this->config->getDataClass()) {
  871.                 $type = TextType::class;
  872.             }
  874.             if (null === $type) {
  875.                 $child = $this->config->getFormFactory()->createForProperty($this->config->getDataClass(), $child, null, $options);
  876.             } else {
  877.                 $child = $this->config->getFormFactory()->createNamed($child, $type, null, $options);
  878.             }
  879.         } elseif ($child->getConfig()->getAutoInitialize()) {
  880.             throw new RuntimeException(sprintf('Automatic initialization is only supported on root forms. You should set the "auto_initialize" option to false on the field "%s".', $child->getName()));
  881.         }
  883.         $this->children[$child->getName()] = $child;
  885.         $child->setParent($this);
  887.         // If setData() is currently being called, there is no need to call
  888.         // mapDataToForms() here, as mapDataToForms() is called at the end
  889.         // of setData() anyway. Not doing this check leads to an endless
  890.         // recursion when initializing the form lazily and an event listener
  891.         // (such as ResizeFormListener) adds fields depending on the data:
  892.         //
  893.         //  * setData() is called, the form is not initialized yet
  894.         //  * add() is called by the listener (setData() is not complete, so
  895.         //    the form is still not initialized)
  896.         //  * getViewData() is called
  897.         //  * setData() is called since the form is not initialized yet
  898.         //  * ... endless recursion ...
  899.         //
  900.         // Also skip data mapping if setData() has not been called yet.
  901.         // setData() will be called upon form initialization and data mapping
  902.         // will take place by then.
  903.         if (!$this->lockSetData && $this->defaultDataSet && !$this->inheritData) {
  904.             $viewData = $this->getViewData();
  905.             $this->config->getDataMapper()->mapDataToForms(
  906.                 $viewData,
  907.                 new \RecursiveIteratorIterator(new InheritDataAwareIterator(new \ArrayIterator([$child->getName() => $child])))
  908.             );
  909.         }
  911.         return $this;
  912.     }
  914.     /**
  915.      * {@inheritdoc}
  916.      */
  917.     public function remove($name)
  918.     {
  919.         if ($this->submitted) {
  920.             throw new AlreadySubmittedException('You cannot remove children from a submitted form.');
  921.         }
  923.         if (isset($this->children[$name])) {
  924.             if (!$this->children[$name]->isSubmitted()) {
  925.                 $this->children[$name]->setParent(null);
  926.             }
  928.             unset($this->children[$name]);
  929.         }
  931.         return $this;
  932.     }
  934.     /**
  935.      * {@inheritdoc}
  936.      */
  937.     public function has($name)
  938.     {
  939.         return isset($this->children[$name]);
  940.     }
  942.     /**
  943.      * {@inheritdoc}
  944.      */
  945.     public function get($name)
  946.     {
  947.         if (isset($this->children[$name])) {
  948.             return $this->children[$name];
  949.         }
  951.         throw new OutOfBoundsException(sprintf('Child "%s" does not exist.', $name));
  952.     }
  954.     /**
  955.      * Returns whether a child with the given name exists (implements the \ArrayAccess interface).
  956.      *
  957.      * @param string $name The name of the child
  958.      *
  959.      * @return bool
  960.      */
  961.     #[\ReturnTypeWillChange]
  962.     public function offsetExists($name)
  963.     {
  964.         return $this->has($name);
  965.     }
  967.     /**
  968.      * Returns the child with the given name (implements the \ArrayAccess interface).
  969.      *
  970.      * @param string $name The name of the child
  971.      *
  972.      * @return FormInterface The child form
  973.      *
  974.      * @throws OutOfBoundsException if the named child does not exist
  975.      */
  976.     #[\ReturnTypeWillChange]
  977.     public function offsetGet($name)
  978.     {
  979.         return $this->get($name);
  980.     }
  982.     /**
  983.      * Adds a child to the form (implements the \ArrayAccess interface).
  984.      *
  985.      * @param string        $name  Ignored. The name of the child is used
  986.      * @param FormInterface $child The child to be added
  987.      *
  988.      * @return void
  989.      *
  990.      * @throws AlreadySubmittedException if the form has already been submitted
  991.      * @throws LogicException            when trying to add a child to a non-compound form
  992.      *
  993.      * @see self::add()
  994.      */
  995.     #[\ReturnTypeWillChange]
  996.     public function offsetSet($name, $child)
  997.     {
  998.         $this->add($child);
  999.     }
  1001.     /**
  1002.      * Removes the child with the given name from the form (implements the \ArrayAccess interface).
  1003.      *
  1004.      * @param string $name The name of the child to remove
  1005.      *
  1006.      * @return void
  1007.      *
  1008.      * @throws AlreadySubmittedException if the form has already been submitted
  1009.      */
  1010.     #[\ReturnTypeWillChange]
  1011.     public function offsetUnset($name)
  1012.     {
  1013.         $this->remove($name);
  1014.     }
  1016.     /**
  1017.      * Returns the iterator for this group.
  1018.      *
  1019.      * @return \Traversable<FormInterface>
  1020.      */
  1021.     #[\ReturnTypeWillChange]
  1022.     public function getIterator()
  1023.     {
  1024.         return $this->children;
  1025.     }
  1027.     /**
  1028.      * Returns the number of form children (implements the \Countable interface).
  1029.      *
  1030.      * @return int The number of embedded form children
  1031.      */
  1032.     #[\ReturnTypeWillChange]
  1033.     public function count()
  1034.     {
  1035.         return \count($this->children);
  1036.     }
  1038.     /**
  1039.      * {@inheritdoc}
  1040.      */
  1041.     public function createView(FormView $parent = null)
  1042.     {
  1043.         if (null === $parent && $this->parent) {
  1044.             $parent = $this->parent->createView();
  1045.         }
  1047.         $type = $this->config->getType();
  1048.         $options = $this->config->getOptions();
  1050.         // The methods createView(), buildView() and finishView() are called
  1051.         // explicitly here in order to be able to override either of them
  1052.         // in a custom resolved form type.
  1053.         $view = $type->createView($this, $parent);
  1055.         $type->buildView($view, $this, $options);
  1057.         foreach ($this->children as $name => $child) {
  1058.             $view->children[$name] = $child->createView($view);
  1059.         }
  1061.         $type->finishView($view, $this, $options);
  1063.         return $view;
  1064.     }
  1066.     /**
  1067.      * Normalizes the underlying data if a model transformer is set.
  1068.      *
  1069.      * @return mixed
  1070.      *
  1071.      * @throws TransformationFailedException If the underlying data cannot be transformed to "normalized" format
  1072.      */
  1073.     private function modelToNorm($value)
  1074.     {
  1075.         try {
  1076.             foreach ($this->config->getModelTransformers() as $transformer) {
  1077.                 $value = $transformer->transform($value);
  1078.             }
  1079.         } catch (TransformationFailedException $exception) {
  1080.             throw new TransformationFailedException(sprintf('Unable to transform data for property path "%s": ', $this->getPropertyPath()).$exception->getMessage(), $exception->getCode(), $exception, $exception->getInvalidMessage(), $exception->getInvalidMessageParameters());
  1081.         }
  1083.         return $value;
  1084.     }
  1086.     /**
  1087.      * Reverse transforms a value if a model transformer is set.
  1088.      *
  1089.      * @return mixed
  1090.      *
  1091.      * @throws TransformationFailedException If the value cannot be transformed to "model" format
  1092.      */
  1093.     private function normToModel($value)
  1094.     {
  1095.         try {
  1096.             $transformers = $this->config->getModelTransformers();
  1098.             for ($i = \count($transformers) - 1; $i >= 0; --$i) {
  1099.                 $value = $transformers[$i]->reverseTransform($value);
  1100.             }
  1101.         } catch (TransformationFailedException $exception) {
  1102.             throw new TransformationFailedException(sprintf('Unable to reverse value for property path "%s": ', $this->getPropertyPath()).$exception->getMessage(), $exception->getCode(), $exception, $exception->getInvalidMessage(), $exception->getInvalidMessageParameters());
  1103.         }
  1105.         return $value;
  1106.     }
  1108.     /**
  1109.      * Transforms the value if a view transformer is set.
  1110.      *
  1111.      * @return mixed
  1112.      *
  1113.      * @throws TransformationFailedException If the normalized value cannot be transformed to "view" format
  1114.      */
  1115.     private function normToView($value)
  1116.     {
  1117.         // Scalar values should  be converted to strings to
  1118.         // facilitate differentiation between empty ("") and zero (0).
  1119.         // Only do this for simple forms, as the resulting value in
  1120.         // compound forms is passed to the data mapper and thus should
  1121.         // not be converted to a string before.
  1122.         if (!($transformers = $this->config->getViewTransformers()) && !$this->config->getCompound()) {
  1123.             return null === $value || is_scalar($value) ? (string) $value : $value;
  1124.         }
  1126.         try {
  1127.             foreach ($transformers as $transformer) {
  1128.                 $value = $transformer->transform($value);
  1129.             }
  1130.         } catch (TransformationFailedException $exception) {
  1131.             throw new TransformationFailedException(sprintf('Unable to transform value for property path "%s": ', $this->getPropertyPath()).$exception->getMessage(), $exception->getCode(), $exception, $exception->getInvalidMessage(), $exception->getInvalidMessageParameters());
  1132.         }
  1134.         return $value;
  1135.     }
  1137.     /**
  1138.      * Reverse transforms a value if a view transformer is set.
  1139.      *
  1140.      * @return mixed
  1141.      *
  1142.      * @throws TransformationFailedException If the submitted value cannot be transformed to "normalized" format
  1143.      */
  1144.     private function viewToNorm($value)
  1145.     {
  1146.         if (!$transformers = $this->config->getViewTransformers()) {
  1147.             return '' === $value ? null : $value;
  1148.         }
  1150.         try {
  1151.             for ($i = \count($transformers) - 1; $i >= 0; --$i) {
  1152.                 $value = $transformers[$i]->reverseTransform($value);
  1153.             }
  1154.         } catch (TransformationFailedException $exception) {
  1155.             throw new TransformationFailedException(sprintf('Unable to reverse value for property path "%s": ', $this->getPropertyPath()).$exception->getMessage(), $exception->getCode(), $exception, $exception->getInvalidMessage(), $exception->getInvalidMessageParameters());
  1156.         }
  1158.         return $value;
  1159.     }
  1160. }