vendor/symfony/form/Form.php line 72

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\Form\Event\PostSetDataEvent;
  15. use Symfony\Component\Form\Event\PostSubmitEvent;
  16. use Symfony\Component\Form\Event\PreSetDataEvent;
  17. use Symfony\Component\Form\Event\PreSubmitEvent;
  18. use Symfony\Component\Form\Event\SubmitEvent;
  19. use Symfony\Component\Form\Exception\AlreadySubmittedException;
  20. use Symfony\Component\Form\Exception\LogicException;
  21. use Symfony\Component\Form\Exception\OutOfBoundsException;
  22. use Symfony\Component\Form\Exception\RuntimeException;
  23. use Symfony\Component\Form\Exception\TransformationFailedException;
  24. use Symfony\Component\Form\Exception\UnexpectedTypeException;
  25. use Symfony\Component\Form\Extension\Core\Type\TextType;
  26. use Symfony\Component\Form\Util\FormUtil;
  27. use Symfony\Component\Form\Util\InheritDataAwareIterator;
  28. use Symfony\Component\Form\Util\OrderedHashMap;
  29. use Symfony\Component\PropertyAccess\PropertyPath;
  30. use Symfony\Component\PropertyAccess\PropertyPathInterface;
  32. /**
  33.  * Form represents a form.
  34.  *
  35.  * To implement your own form fields, you need to have a thorough understanding
  36.  * of the data flow within a form. A form stores its data in three different
  37.  * representations:
  38.  *
  39.  *   (1) the "model" format required by the form's object
  40.  *   (2) the "normalized" format for internal processing
  41.  *   (3) the "view" format used for display simple fields
  42.  *       or map children model data for compound fields
  43.  *
  44.  * A date field, for example, may store a date as "Y-m-d" string (1) in the
  45.  * object. To facilitate processing in the field, this value is normalized
  46.  * to a DateTime object (2). In the HTML representation of your form, a
  47.  * localized string (3) may be presented to and modified by the user, or it could be an array of values
  48.  * to be mapped to choices fields.
  49.  *
  50.  * In most cases, format (1) and format (2) will be the same. For example,
  51.  * a checkbox field uses a Boolean value for both internal processing and
  52.  * storage in the object. In these cases you need to set a view transformer
  53.  * to convert between formats (2) and (3). You can do this by calling
  54.  * addViewTransformer().
  55.  *
  56.  * In some cases though it makes sense to make format (1) configurable. To
  57.  * demonstrate this, let's extend our above date field to store the value
  58.  * either as "Y-m-d" string or as timestamp. Internally we still want to
  59.  * use a DateTime object for processing. To convert the data from string/integer
  60.  * to DateTime you can set a model transformer by calling
  61.  * addModelTransformer(). The normalized data is then converted to the displayed
  62.  * data as described before.
  63.  *
  64.  * The conversions (1) -> (2) -> (3) use the transform methods of the transformers.
  65.  * The conversions (3) -> (2) -> (1) use the reverseTransform methods of the transformers.
  66.  *
  67.  * @author Fabien Potencier <fabien@symfony.com>
  68.  * @author Bernhard Schussek <bschussek@gmail.com>
  69.  *
  70.  * @implements \IteratorAggregate<string, FormInterface>
  71.  */
  72. class Form implements \IteratorAggregate, FormInterface, ClearableErrorsInterface
  73. {
  74.     private $config;
  75.     private $parent = null;
  77.     /**
  78.      * A map of FormInterface instances.
  79.      *
  80.      * @var OrderedHashMap<string, FormInterface>
  81.      */
  82.     private $children;
  84.     /**
  85.      * @var FormError[]
  86.      */
  87.     private array $errors = [];
  89.     private bool $submitted = false;
  91.     /**
  92.      * The button that was used to submit the form.
  93.      */
  94.     private $clickedButton = null;
  96.     private mixed $modelData = null;
  97.     private mixed $normData = null;
  98.     private mixed $viewData = null;
  100.     /**
  101.      * The submitted values that don't belong to any children.
  102.      */
  103.     private array $extraData = [];
  105.     /**
  106.      * The transformation failure generated during submission, if any.
  107.      */
  108.     private $transformationFailure = null;
  110.     /**
  111.      * Whether the form's data has been initialized.
  112.      *
  113.      * When the data is initialized with its default value, that default value
  114.      * is passed through the transformer chain in order to synchronize the
  115.      * model, normalized and view format for the first time. This is done
  116.      * lazily in order to save performance when {@link setData()} is called
  117.      * manually, making the initialization with the configured default value
  118.      * superfluous.
  119.      */
  120.     private bool $defaultDataSet = false;
  122.     /**
  123.      * Whether setData() is currently being called.
  124.      */
  125.     private bool $lockSetData = false;
  127.     private string $name = '';
  129.     /**
  130.      * Whether the form inherits its underlying data from its parent.
  131.      */
  132.     private bool $inheritData;
  134.     private $propertyPath = null;
  136.     /**
  137.      * @throws LogicException if a data mapper is not provided for a compound form
  138.      */
  139.     public function __construct(FormConfigInterface $config)
  140.     {
  141.         // Compound forms always need a data mapper, otherwise calls to
  142.         // `setData` and `add` will not lead to the correct population of
  143.         // the child forms.
  144.         if ($config->getCompound() && !$config->getDataMapper()) {
  145.             throw new LogicException('Compound forms need a data mapper.');
  146.         }
  148.         // If the form inherits the data from its parent, it is not necessary
  149.         // to call setData() with the default data.
  150.         if ($this->inheritData = $config->getInheritData()) {
  151.             $this->defaultDataSet = true;
  152.         }
  154.         $this->config = $config;
  155.         $this->children = new OrderedHashMap();
  156.         $this->name = $config->getName();
  157.     }
  159.     public function __clone()
  160.     {
  161.         $this->children = clone $this->children;
  163.         foreach ($this->children as $key => $child) {
  164.             $this->children[$key] = clone $child;
  165.         }
  166.     }
  168.     /**
  169.      * {@inheritdoc}
  170.      */
  171.     public function getConfig(): FormConfigInterface
  172.     {
  173.         return $this->config;
  174.     }
  176.     /**
  177.      * {@inheritdoc}
  178.      */
  179.     public function getName(): string
  180.     {
  181.         return $this->name;
  182.     }
  184.     /**
  185.      * {@inheritdoc}
  186.      */
  187.     public function getPropertyPath(): ?PropertyPathInterface
  188.     {
  189.         if ($this->propertyPath || $this->propertyPath = $this->config->getPropertyPath()) {
  190.             return $this->propertyPath;
  191.         }
  193.         if ('' === $this->name) {
  194.             return null;
  195.         }
  197.         $parent = $this->parent;
  199.         while ($parent && $parent->getConfig()->getInheritData()) {
  200.             $parent = $parent->getParent();
  201.         }
  203.         if ($parent && null === $parent->getConfig()->getDataClass()) {
  204.             $this->propertyPath = new PropertyPath('['.$this->name.']');
  205.         } else {
  206.             $this->propertyPath = new PropertyPath($this->name);
  207.         }
  209.         return $this->propertyPath;
  210.     }
  212.     /**
  213.      * {@inheritdoc}
  214.      */
  215.     public function isRequired(): bool
  216.     {
  217.         if (null === $this->parent || $this->parent->isRequired()) {
  218.             return $this->config->getRequired();
  219.         }
  221.         return false;
  222.     }
  224.     /**
  225.      * {@inheritdoc}
  226.      */
  227.     public function isDisabled(): bool
  228.     {
  229.         if (null === $this->parent || !$this->parent->isDisabled()) {
  230.             return $this->config->getDisabled();
  231.         }
  233.         return true;
  234.     }
  236.     /**
  237.      * {@inheritdoc}
  238.      */
  239.     public function setParent(FormInterface $parent = null): static
  240.     {
  241.         if ($this->submitted) {
  242.             throw new AlreadySubmittedException('You cannot set the parent of a submitted form.');
  243.         }
  245.         if (null !== $parent && '' === $this->name) {
  246.             throw new LogicException('A form with an empty name cannot have a parent form.');
  247.         }
  249.         $this->parent = $parent;
  251.         return $this;
  252.     }
  254.     /**
  255.      * {@inheritdoc}
  256.      */
  257.     public function getParent(): ?FormInterface
  258.     {
  259.         return $this->parent;
  260.     }
  262.     /**
  263.      * {@inheritdoc}
  264.      */
  265.     public function getRoot(): FormInterface
  266.     {
  267.         return $this->parent ? $this->parent->getRoot() : $this;
  268.     }
  270.     /**
  271.      * {@inheritdoc}
  272.      */
  273.     public function isRoot(): bool
  274.     {
  275.         return null === $this->parent;
  276.     }
  278.     /**
  279.      * {@inheritdoc}
  280.      */
  281.     public function setData(mixed $modelData): static
  282.     {
  283.         // If the form is submitted while disabled, it is set to submitted, but the data is not
  284.         // changed. In such cases (i.e. when the form is not initialized yet) don't
  285.         // abort this method.
  286.         if ($this->submitted && $this->defaultDataSet) {
  287.             throw new AlreadySubmittedException('You cannot change the data of a submitted form.');
  288.         }
  290.         // If the form inherits its parent's data, disallow data setting to
  291.         // prevent merge conflicts
  292.         if ($this->inheritData) {
  293.             throw new RuntimeException('You cannot change the data of a form inheriting its parent data.');
  294.         }
  296.         // Don't allow modifications of the configured data if the data is locked
  297.         if ($this->config->getDataLocked() && $modelData !== $this->config->getData()) {
  298.             return $this;
  299.         }
  301.         if (\is_object($modelData) && !$this->config->getByReference()) {
  302.             $modelData = clone $modelData;
  303.         }
  305.         if ($this->lockSetData) {
  306.             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.');
  307.         }
  309.         $this->lockSetData = true;
  310.         $dispatcher = $this->config->getEventDispatcher();
  312.         // Hook to change content of the model data before transformation and mapping children
  313.         if ($dispatcher->hasListeners(FormEvents::PRE_SET_DATA)) {
  314.             $event = new PreSetDataEvent($this, $modelData);
  315.             $dispatcher->dispatch($event, FormEvents::PRE_SET_DATA);
  316.             $modelData = $event->getData();
  317.         }
  319.         // Treat data as strings unless a transformer exists
  320.         if (\is_scalar($modelData) && !$this->config->getViewTransformers() && !$this->config->getModelTransformers()) {
  321.             $modelData = (string) $modelData;
  322.         }
  324.         // Synchronize representations - must not change the content!
  325.         // Transformation exceptions are not caught on initialization
  326.         $normData = $this->modelToNorm($modelData);
  327.         $viewData = $this->normToView($normData);
  329.         // Validate if view data matches data class (unless empty)
  330.         if (!FormUtil::isEmpty($viewData)) {
  331.             $dataClass = $this->config->getDataClass();
  333.             if (null !== $dataClass && !$viewData instanceof $dataClass) {
  334.                 $actualType = get_debug_type($viewData);
  336.                 throw new LogicException('The form\'s view data is expected to be a "'.$dataClass.'", but it is a "'.$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.'".');
  337.             }
  338.         }
  340.         $this->modelData = $modelData;
  341.         $this->normData = $normData;
  342.         $this->viewData = $viewData;
  343.         $this->defaultDataSet = true;
  344.         $this->lockSetData = false;
  346.         // Compound forms don't need to invoke this method if they don't have children
  347.         if (\count($this->children) > 0) {
  348.             // Update child forms from the data (unless their config data is locked)
  349.             $this->config->getDataMapper()->mapDataToForms($viewData, new \RecursiveIteratorIterator(new InheritDataAwareIterator($this->children)));
  350.         }
  352.         if ($dispatcher->hasListeners(FormEvents::POST_SET_DATA)) {
  353.             $event = new PostSetDataEvent($this, $modelData);
  354.             $dispatcher->dispatch($event, FormEvents::POST_SET_DATA);
  355.         }
  357.         return $this;
  358.     }
  360.     /**
  361.      * {@inheritdoc}
  362.      */
  363.     public function getData(): mixed
  364.     {
  365.         if ($this->inheritData) {
  366.             if (!$this->parent) {
  367.                 throw new RuntimeException('The form is configured to inherit its parent\'s data, but does not have a parent.');
  368.             }
  370.             return $this->parent->getData();
  371.         }
  373.         if (!$this->defaultDataSet) {
  374.             if ($this->lockSetData) {
  375.                 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.');
  376.             }
  378.             $this->setData($this->config->getData());
  379.         }
  381.         return $this->modelData;
  382.     }
  384.     /**
  385.      * {@inheritdoc}
  386.      */
  387.     public function getNormData(): mixed
  388.     {
  389.         if ($this->inheritData) {
  390.             if (!$this->parent) {
  391.                 throw new RuntimeException('The form is configured to inherit its parent\'s data, but does not have a parent.');
  392.             }
  394.             return $this->parent->getNormData();
  395.         }
  397.         if (!$this->defaultDataSet) {
  398.             if ($this->lockSetData) {
  399.                 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.');
  400.             }
  402.             $this->setData($this->config->getData());
  403.         }
  405.         return $this->normData;
  406.     }
  408.     /**
  409.      * {@inheritdoc}
  410.      */
  411.     public function getViewData(): mixed
  412.     {
  413.         if ($this->inheritData) {
  414.             if (!$this->parent) {
  415.                 throw new RuntimeException('The form is configured to inherit its parent\'s data, but does not have a parent.');
  416.             }
  418.             return $this->parent->getViewData();
  419.         }
  421.         if (!$this->defaultDataSet) {
  422.             if ($this->lockSetData) {
  423.                 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.');
  424.             }
  426.             $this->setData($this->config->getData());
  427.         }
  429.         return $this->viewData;
  430.     }
  432.     /**
  433.      * {@inheritdoc}
  434.      */
  435.     public function getExtraData(): array
  436.     {
  437.         return $this->extraData;
  438.     }
  440.     /**
  441.      * {@inheritdoc}
  442.      */
  443.     public function initialize(): static
  444.     {
  445.         if (null !== $this->parent) {
  446.             throw new RuntimeException('Only root forms should be initialized.');
  447.         }
  449.         // Guarantee that the *_SET_DATA events have been triggered once the
  450.         // form is initialized. This makes sure that dynamically added or
  451.         // removed fields are already visible after initialization.
  452.         if (!$this->defaultDataSet) {
  453.             $this->setData($this->config->getData());
  454.         }
  456.         return $this;
  457.     }
  459.     /**
  460.      * {@inheritdoc}
  461.      */
  462.     public function handleRequest(mixed $request = null): static
  463.     {
  464.         $this->config->getRequestHandler()->handleRequest($this, $request);
  466.         return $this;
  467.     }
  469.     /**
  470.      * {@inheritdoc}
  471.      */
  472.     public function submit(mixed $submittedData, bool $clearMissing = true): static
  473.     {
  474.         if ($this->submitted) {
  475.             throw new AlreadySubmittedException('A form can only be submitted once.');
  476.         }
  478.         // Initialize errors in the very beginning so we're sure
  479.         // they are collectable during submission only
  480.         $this->errors = [];
  482.         // Obviously, a disabled form should not change its data upon submission.
  483.         if ($this->isDisabled()) {
  484.             $this->submitted = true;
  486.             return $this;
  487.         }
  489.         // The data must be initialized if it was not initialized yet.
  490.         // This is necessary to guarantee that the *_SET_DATA listeners
  491.         // are always invoked before submit() takes place.
  492.         if (!$this->defaultDataSet) {
  493.             $this->setData($this->config->getData());
  494.         }
  496.         // Treat false as NULL to support binding false to checkboxes.
  497.         // Don't convert NULL to a string here in order to determine later
  498.         // whether an empty value has been submitted or whether no value has
  499.         // been submitted at all. This is important for processing checkboxes
  500.         // and radio buttons with empty values.
  501.         if (false === $submittedData) {
  502.             $submittedData = null;
  503.         } elseif (\is_scalar($submittedData)) {
  504.             $submittedData = (string) $submittedData;
  505.         } elseif ($this->config->getRequestHandler()->isFileUpload($submittedData)) {
  506.             if (!$this->config->getOption('allow_file_upload')) {
  507.                 $submittedData = null;
  508.                 $this->transformationFailure = new TransformationFailedException('Submitted data was expected to be text or number, file upload given.');
  509.             }
  510.         } elseif (\is_array($submittedData) && !$this->config->getCompound() && !$this->config->getOption('multiple', false)) {
  511.             $submittedData = null;
  512.             $this->transformationFailure = new TransformationFailedException('Submitted data was expected to be text or number, array given.');
  513.         }
  515.         $dispatcher = $this->config->getEventDispatcher();
  517.         $modelData = null;
  518.         $normData = null;
  519.         $viewData = null;
  521.         try {
  522.             if (null !== $this->transformationFailure) {
  523.                 throw $this->transformationFailure;
  524.             }
  526.             // Hook to change content of the data submitted by the browser
  527.             if ($dispatcher->hasListeners(FormEvents::PRE_SUBMIT)) {
  528.                 $event = new PreSubmitEvent($this, $submittedData);
  529.                 $dispatcher->dispatch($event, FormEvents::PRE_SUBMIT);
  530.                 $submittedData = $event->getData();
  531.             }
  533.             // Check whether the form is compound.
  534.             // This check is preferable over checking the number of children,
  535.             // since forms without children may also be compound.
  536.             // (think of empty collection forms)
  537.             if ($this->config->getCompound()) {
  538.                 if (null === $submittedData) {
  539.                     $submittedData = [];
  540.                 }
  542.                 if (!\is_array($submittedData)) {
  543.                     throw new TransformationFailedException('Compound forms expect an array or NULL on submission.');
  544.                 }
  546.                 foreach ($this->children as $name => $child) {
  547.                     $isSubmitted = \array_key_exists($name, $submittedData);
  549.                     if ($isSubmitted || $clearMissing) {
  550.                         $child->submit($isSubmitted ? $submittedData[$name] : null, $clearMissing);
  551.                         unset($submittedData[$name]);
  553.                         if (null !== $this->clickedButton) {
  554.                             continue;
  555.                         }
  557.                         if ($child instanceof ClickableInterface && $child->isClicked()) {
  558.                             $this->clickedButton = $child;
  560.                             continue;
  561.                         }
  563.                         if (method_exists($child, 'getClickedButton') && null !== $child->getClickedButton()) {
  564.                             $this->clickedButton = $child->getClickedButton();
  565.                         }
  566.                     }
  567.                 }
  569.                 $this->extraData = $submittedData;
  570.             }
  572.             // Forms that inherit their parents' data also are not processed,
  573.             // because then it would be too difficult to merge the changes in
  574.             // the child and the parent form. Instead, the parent form also takes
  575.             // changes in the grandchildren (i.e. children of the form that inherits
  576.             // its parent's data) into account.
  577.             // (see InheritDataAwareIterator below)
  578.             if (!$this->inheritData) {
  579.                 // If the form is compound, the view data is merged with the data
  580.                 // of the children using the data mapper.
  581.                 // If the form is not compound, the view data is assigned to the submitted data.
  582.                 $viewData = $this->config->getCompound() ? $this->viewData : $submittedData;
  584.                 if (FormUtil::isEmpty($viewData)) {
  585.                     $emptyData = $this->config->getEmptyData();
  587.                     if ($emptyData instanceof \Closure) {
  588.                         $emptyData = $emptyData($this, $viewData);
  589.                     }
  591.                     $viewData = $emptyData;
  592.                 }
  594.                 // Merge form data from children into existing view data
  595.                 // It is not necessary to invoke this method if the form has no children,
  596.                 // even if it is compound.
  597.                 if (\count($this->children) > 0) {
  598.                     // Use InheritDataAwareIterator to process children of
  599.                     // descendants that inherit this form's data.
  600.                     // These descendants will not be submitted normally (see the check
  601.                     // for $this->config->getInheritData() above)
  602.                     $this->config->getDataMapper()->mapFormsToData(
  603.                         new \RecursiveIteratorIterator(new InheritDataAwareIterator($this->children)),
  604.                         $viewData
  605.                     );
  606.                 }
  608.                 // Normalize data to unified representation
  609.                 $normData = $this->viewToNorm($viewData);
  611.                 // Hook to change content of the data in the normalized
  612.                 // representation
  613.                 if ($dispatcher->hasListeners(FormEvents::SUBMIT)) {
  614.                     $event = new SubmitEvent($this, $normData);
  615.                     $dispatcher->dispatch($event, FormEvents::SUBMIT);
  616.                     $normData = $event->getData();
  617.                 }
  619.                 // Synchronize representations - must not change the content!
  620.                 $modelData = $this->normToModel($normData);
  621.                 $viewData = $this->normToView($normData);
  622.             }
  623.         } catch (TransformationFailedException $e) {
  624.             $this->transformationFailure = $e;
  626.             // If $viewData was not yet set, set it to $submittedData so that
  627.             // the erroneous data is accessible on the form.
  628.             // Forms that inherit data never set any data, because the getters
  629.             // forward to the parent form's getters anyway.
  630.             if (null === $viewData && !$this->inheritData) {
  631.                 $viewData = $submittedData;
  632.             }
  633.         }
  635.         $this->submitted = true;
  636.         $this->modelData = $modelData;
  637.         $this->normData = $normData;
  638.         $this->viewData = $viewData;
  640.         if ($dispatcher->hasListeners(FormEvents::POST_SUBMIT)) {
  641.             $event = new PostSubmitEvent($this, $viewData);
  642.             $dispatcher->dispatch($event, FormEvents::POST_SUBMIT);
  643.         }
  645.         return $this;
  646.     }
  648.     /**
  649.      * {@inheritdoc}
  650.      */
  651.     public function addError(FormError $error): static
  652.     {
  653.         if (null === $error->getOrigin()) {
  654.             $error->setOrigin($this);
  655.         }
  657.         if ($this->parent && $this->config->getErrorBubbling()) {
  658.             $this->parent->addError($error);
  659.         } else {
  660.             $this->errors[] = $error;
  661.         }
  663.         return $this;
  664.     }
  666.     /**
  667.      * {@inheritdoc}
  668.      */
  669.     public function isSubmitted(): bool
  670.     {
  671.         return $this->submitted;
  672.     }
  674.     /**
  675.      * {@inheritdoc}
  676.      */
  677.     public function isSynchronized(): bool
  678.     {
  679.         return null === $this->transformationFailure;
  680.     }
  682.     /**
  683.      * {@inheritdoc}
  684.      */
  685.     public function getTransformationFailure(): ?Exception\TransformationFailedException
  686.     {
  687.         return $this->transformationFailure;
  688.     }
  690.     /**
  691.      * {@inheritdoc}
  692.      */
  693.     public function isEmpty(): bool
  694.     {
  695.         foreach ($this->children as $child) {
  696.             if (!$child->isEmpty()) {
  697.                 return false;
  698.             }
  699.         }
  701.         if (null !== $isEmptyCallback = $this->config->getIsEmptyCallback()) {
  702.             return $isEmptyCallback($this->modelData);
  703.         }
  705.         return FormUtil::isEmpty($this->modelData) ||
  706.             // arrays, countables
  707.             ((\is_array($this->modelData) || $this->modelData instanceof \Countable) && 0 === \count($this->modelData)) ||
  708.             // traversables that are not countable
  709.             ($this->modelData instanceof \Traversable && 0 === iterator_count($this->modelData));
  710.     }
  712.     /**
  713.      * {@inheritdoc}
  714.      */
  715.     public function isValid(): bool
  716.     {
  717.         if (!$this->submitted) {
  718.             throw new LogicException('Cannot check if an unsubmitted form is valid. Call Form::isSubmitted() before Form::isValid().');
  719.         }
  721.         if ($this->isDisabled()) {
  722.             return true;
  723.         }
  725.         return 0 === \count($this->getErrors(true));
  726.     }
  728.     /**
  729.      * Returns the button that was used to submit the form.
  730.      */
  731.     public function getClickedButton(): FormInterface|ClickableInterface|null
  732.     {
  733.         if ($this->clickedButton) {
  734.             return $this->clickedButton;
  735.         }
  737.         return $this->parent && method_exists($this->parent, 'getClickedButton') ? $this->parent->getClickedButton() : null;
  738.     }
  740.     /**
  741.      * {@inheritdoc}
  742.      */
  743.     public function getErrors(bool $deep = false, bool $flatten = true): FormErrorIterator
  744.     {
  745.         $errors = $this->errors;
  747.         // Copy the errors of nested forms to the $errors array
  748.         if ($deep) {
  749.             foreach ($this as $child) {
  750.                 /** @var FormInterface $child */
  751.                 if ($child->isSubmitted() && $child->isValid()) {
  752.                     continue;
  753.                 }
  755.                 $iterator = $child->getErrors(true, $flatten);
  757.                 if (0 === \count($iterator)) {
  758.                     continue;
  759.                 }
  761.                 if ($flatten) {
  762.                     foreach ($iterator as $error) {
  763.                         $errors[] = $error;
  764.                     }
  765.                 } else {
  766.                     $errors[] = $iterator;
  767.                 }
  768.             }
  769.         }
  771.         return new FormErrorIterator($this, $errors);
  772.     }
  774.     /**
  775.      * {@inheritdoc}
  776.      */
  777.     public function clearErrors(bool $deep = false): static
  778.     {
  779.         $this->errors = [];
  781.         if ($deep) {
  782.             // Clear errors from children
  783.             foreach ($this as $child) {
  784.                 if ($child instanceof ClearableErrorsInterface) {
  785.                     $child->clearErrors(true);
  786.                 }
  787.             }
  788.         }
  790.         return $this;
  791.     }
  793.     /**
  794.      * {@inheritdoc}
  795.      */
  796.     public function all(): array
  797.     {
  798.         return iterator_to_array($this->children);
  799.     }
  801.     /**
  802.      * {@inheritdoc}
  803.      */
  804.     public function add(FormInterface|string $child, string $type = null, array $options = []): static
  805.     {
  806.         if ($this->submitted) {
  807.             throw new AlreadySubmittedException('You cannot add children to a submitted form.');
  808.         }
  810.         if (!$this->config->getCompound()) {
  811.             throw new LogicException('You cannot add children to a simple form. Maybe you should set the option "compound" to true?');
  812.         }
  814.         if (!$child instanceof FormInterface) {
  815.             if (!\is_string($child) && !\is_int($child)) {
  816.                 throw new UnexpectedTypeException($child, 'string or Symfony\Component\Form\FormInterface');
  817.             }
  819.             $child = (string) $child;
  821.             if (null !== $type && !\is_string($type)) {
  822.                 throw new UnexpectedTypeException($type, 'string or null');
  823.             }
  825.             // Never initialize child forms automatically
  826.             $options['auto_initialize'] = false;
  828.             if (null === $type && null === $this->config->getDataClass()) {
  829.                 $type = TextType::class;
  830.             }
  832.             if (null === $type) {
  833.                 $child = $this->config->getFormFactory()->createForProperty($this->config->getDataClass(), $child, null, $options);
  834.             } else {
  835.                 $child = $this->config->getFormFactory()->createNamed($child, $type, null, $options);
  836.             }
  837.         } elseif ($child->getConfig()->getAutoInitialize()) {
  838.             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()));
  839.         }
  841.         $this->children[$child->getName()] = $child;
  843.         $child->setParent($this);
  845.         // If setData() is currently being called, there is no need to call
  846.         // mapDataToForms() here, as mapDataToForms() is called at the end
  847.         // of setData() anyway. Not doing this check leads to an endless
  848.         // recursion when initializing the form lazily and an event listener
  849.         // (such as ResizeFormListener) adds fields depending on the data:
  850.         //
  851.         //  * setData() is called, the form is not initialized yet
  852.         //  * add() is called by the listener (setData() is not complete, so
  853.         //    the form is still not initialized)
  854.         //  * getViewData() is called
  855.         //  * setData() is called since the form is not initialized yet
  856.         //  * ... endless recursion ...
  857.         //
  858.         // Also skip data mapping if setData() has not been called yet.
  859.         // setData() will be called upon form initialization and data mapping
  860.         // will take place by then.
  861.         if (!$this->lockSetData && $this->defaultDataSet && !$this->inheritData) {
  862.             $viewData = $this->getViewData();
  863.             $this->config->getDataMapper()->mapDataToForms(
  864.                 $viewData,
  865.                 new \RecursiveIteratorIterator(new InheritDataAwareIterator(new \ArrayIterator([$child->getName() => $child])))
  866.             );
  867.         }
  869.         return $this;
  870.     }
  872.     /**
  873.      * {@inheritdoc}
  874.      */
  875.     public function remove(string $name): static
  876.     {
  877.         if ($this->submitted) {
  878.             throw new AlreadySubmittedException('You cannot remove children from a submitted form.');
  879.         }
  881.         if (isset($this->children[$name])) {
  882.             if (!$this->children[$name]->isSubmitted()) {
  883.                 $this->children[$name]->setParent(null);
  884.             }
  886.             unset($this->children[$name]);
  887.         }
  889.         return $this;
  890.     }
  892.     /**
  893.      * {@inheritdoc}
  894.      */
  895.     public function has(string $name): bool
  896.     {
  897.         return isset($this->children[$name]);
  898.     }
  900.     /**
  901.      * {@inheritdoc}
  902.      */
  903.     public function get(string $name): FormInterface
  904.     {
  905.         if (isset($this->children[$name])) {
  906.             return $this->children[$name];
  907.         }
  909.         throw new OutOfBoundsException(sprintf('Child "%s" does not exist.', $name));
  910.     }
  912.     /**
  913.      * Returns whether a child with the given name exists (implements the \ArrayAccess interface).
  914.      *
  915.      * @param string $name The name of the child
  916.      */
  917.     public function offsetExists(mixed $name): bool
  918.     {
  919.         return $this->has($name);
  920.     }
  922.     /**
  923.      * Returns the child with the given name (implements the \ArrayAccess interface).
  924.      *
  925.      * @param string $name The name of the child
  926.      *
  927.      * @throws OutOfBoundsException if the named child does not exist
  928.      */
  929.     public function offsetGet(mixed $name): FormInterface
  930.     {
  931.         return $this->get($name);
  932.     }
  934.     /**
  935.      * Adds a child to the form (implements the \ArrayAccess interface).
  936.      *
  937.      * @param string        $name  Ignored. The name of the child is used
  938.      * @param FormInterface $child The child to be added
  939.      *
  940.      * @throws AlreadySubmittedException if the form has already been submitted
  941.      * @throws LogicException            when trying to add a child to a non-compound form
  942.      *
  943.      * @see self::add()
  944.      */
  945.     public function offsetSet(mixed $name, mixed $child): void
  946.     {
  947.         $this->add($child);
  948.     }
  950.     /**
  951.      * Removes the child with the given name from the form (implements the \ArrayAccess interface).
  952.      *
  953.      * @param string $name The name of the child to remove
  954.      *
  955.      * @throws AlreadySubmittedException if the form has already been submitted
  956.      */
  957.     public function offsetUnset(mixed $name): void
  958.     {
  959.         $this->remove($name);
  960.     }
  962.     /**
  963.      * Returns the iterator for this group.
  964.      *
  965.      * @return \Traversable<string, FormInterface>
  966.      */
  967.     public function getIterator(): \Traversable
  968.     {
  969.         return $this->children;
  970.     }
  972.     /**
  973.      * Returns the number of form children (implements the \Countable interface).
  974.      */
  975.     public function count(): int
  976.     {
  977.         return \count($this->children);
  978.     }
  980.     /**
  981.      * {@inheritdoc}
  982.      */
  983.     public function createView(FormView $parent = null): FormView
  984.     {
  985.         if (null === $parent && $this->parent) {
  986.             $parent = $this->parent->createView();
  987.         }
  989.         $type = $this->config->getType();
  990.         $options = $this->config->getOptions();
  992.         // The methods createView(), buildView() and finishView() are called
  993.         // explicitly here in order to be able to override either of them
  994.         // in a custom resolved form type.
  995.         $view = $type->createView($this, $parent);
  997.         $type->buildView($view, $this, $options);
  999.         foreach ($this->children as $name => $child) {
  1000.             $view->children[$name] = $child->createView($view);
  1001.         }
  1003.         $this->sort($view->children);
  1005.         $type->finishView($view, $this, $options);
  1007.         return $view;
  1008.     }
  1010.     /**
  1011.      * Sorts view fields based on their priority value.
  1012.      */
  1013.     private function sort(array &$children): void
  1014.     {
  1015.         $c = [];
  1016.         $i = 0;
  1017.         $needsSorting = false;
  1018.         foreach ($children as $name => $child) {
  1019.             $c[$name] = ['p' => $child->vars['priority'] ?? 0, 'i' => $i++];
  1021.             if (0 !== $c[$name]['p']) {
  1022.                 $needsSorting = true;
  1023.             }
  1024.         }
  1026.         if (!$needsSorting) {
  1027.             return;
  1028.         }
  1030.         uksort($children, static function ($a, $b) use ($c): int {
  1031.             return [$c[$b]['p'], $c[$a]['i']] <=> [$c[$a]['p'], $c[$b]['i']];
  1032.         });
  1033.     }
  1035.     /**
  1036.      * Normalizes the underlying data if a model transformer is set.
  1037.      *
  1038.      * @throws TransformationFailedException If the underlying data cannot be transformed to "normalized" format
  1039.      */
  1040.     private function modelToNorm(mixed $value): mixed
  1041.     {
  1042.         try {
  1043.             foreach ($this->config->getModelTransformers() as $transformer) {
  1044.                 $value = $transformer->transform($value);
  1045.             }
  1046.         } catch (TransformationFailedException $exception) {
  1047.             throw new TransformationFailedException(sprintf('Unable to transform data for property path "%s": ', $this->getPropertyPath()).$exception->getMessage(), $exception->getCode(), $exception, $exception->getInvalidMessage(), $exception->getInvalidMessageParameters());
  1048.         }
  1050.         return $value;
  1051.     }
  1053.     /**
  1054.      * Reverse transforms a value if a model transformer is set.
  1055.      *
  1056.      * @throws TransformationFailedException If the value cannot be transformed to "model" format
  1057.      */
  1058.     private function normToModel(mixed $value): mixed
  1059.     {
  1060.         try {
  1061.             $transformers = $this->config->getModelTransformers();
  1063.             for ($i = \count($transformers) - 1; $i >= 0; --$i) {
  1064.                 $value = $transformers[$i]->reverseTransform($value);
  1065.             }
  1066.         } catch (TransformationFailedException $exception) {
  1067.             throw new TransformationFailedException(sprintf('Unable to reverse value for property path "%s": ', $this->getPropertyPath()).$exception->getMessage(), $exception->getCode(), $exception, $exception->getInvalidMessage(), $exception->getInvalidMessageParameters());
  1068.         }
  1070.         return $value;
  1071.     }
  1073.     /**
  1074.      * Transforms the value if a view transformer is set.
  1075.      *
  1076.      * @throws TransformationFailedException If the normalized value cannot be transformed to "view" format
  1077.      */
  1078.     private function normToView(mixed $value): mixed
  1079.     {
  1080.         // Scalar values should  be converted to strings to
  1081.         // facilitate differentiation between empty ("") and zero (0).
  1082.         // Only do this for simple forms, as the resulting value in
  1083.         // compound forms is passed to the data mapper and thus should
  1084.         // not be converted to a string before.
  1085.         if (!($transformers = $this->config->getViewTransformers()) && !$this->config->getCompound()) {
  1086.             return null === $value || \is_scalar($value) ? (string) $value : $value;
  1087.         }
  1089.         try {
  1090.             foreach ($transformers as $transformer) {
  1091.                 $value = $transformer->transform($value);
  1092.             }
  1093.         } catch (TransformationFailedException $exception) {
  1094.             throw new TransformationFailedException(sprintf('Unable to transform value for property path "%s": ', $this->getPropertyPath()).$exception->getMessage(), $exception->getCode(), $exception, $exception->getInvalidMessage(), $exception->getInvalidMessageParameters());
  1095.         }
  1097.         return $value;
  1098.     }
  1100.     /**
  1101.      * Reverse transforms a value if a view transformer is set.
  1102.      *
  1103.      * @throws TransformationFailedException If the submitted value cannot be transformed to "normalized" format
  1104.      */
  1105.     private function viewToNorm(mixed $value): mixed
  1106.     {
  1107.         if (!$transformers = $this->config->getViewTransformers()) {
  1108.             return '' === $value ? null : $value;
  1109.         }
  1111.         try {
  1112.             for ($i = \count($transformers) - 1; $i >= 0; --$i) {
  1113.                 $value = $transformers[$i]->reverseTransform($value);
  1114.             }
  1115.         } catch (TransformationFailedException $exception) {
  1116.             throw new TransformationFailedException(sprintf('Unable to reverse value for property path "%s": ', $this->getPropertyPath()).$exception->getMessage(), $exception->getCode(), $exception, $exception->getInvalidMessage(), $exception->getInvalidMessageParameters());
  1117.         }
  1119.         return $value;
  1120.     }
  1121. }