name: Form class_comment: '# * Form represents a form. # * # * To implement your own form fields, you need to have a thorough understanding # * of the data flow within a form. A form stores its data in three different # * representations: # * # * (1) the "model" format required by the form''s object # * (2) the "normalized" format for internal processing # * (3) the "view" format used for display simple fields # * or map children model data for compound fields # * # * 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) may be presented to and modified by the user, or it could be an array of values # * to be mapped to choices fields. # * # * In most cases, format (1) and format (2) will be the same. For example, # * a checkbox field uses a Boolean value for both internal processing and # * storage in the object. In these cases you need to set a view transformer # * to convert between formats (2) and (3). You can do this by calling # * addViewTransformer(). # * # * In some cases though it makes sense to make format (1) configurable. To # * demonstrate this, let''s extend our above date field to store the value # * either as "Y-m-d" string or as timestamp. Internally we still want to # * use a DateTime object for processing. To convert the data from string/integer # * to DateTime you can set a model transformer by calling # * addModelTransformer(). The normalized data is then converted to the displayed # * data as described before. # * # * The conversions (1) -> (2) -> (3) use the transform methods of the transformers. # * The conversions (3) -> (2) -> (1) use the reverseTransform methods of the transformers. # * # * @author Fabien Potencier # * @author Bernhard Schussek # * # * @implements \IteratorAggregate' dependencies: - name: PostSetDataEvent type: class source: Symfony\Component\Form\Event\PostSetDataEvent - name: PostSubmitEvent type: class source: Symfony\Component\Form\Event\PostSubmitEvent - name: PreSetDataEvent type: class source: Symfony\Component\Form\Event\PreSetDataEvent - name: PreSubmitEvent type: class source: Symfony\Component\Form\Event\PreSubmitEvent - name: SubmitEvent type: class source: Symfony\Component\Form\Event\SubmitEvent - name: AlreadySubmittedException type: class source: Symfony\Component\Form\Exception\AlreadySubmittedException - name: LogicException type: class source: Symfony\Component\Form\Exception\LogicException - name: OutOfBoundsException type: class source: Symfony\Component\Form\Exception\OutOfBoundsException - name: RuntimeException type: class source: Symfony\Component\Form\Exception\RuntimeException - name: TransformationFailedException type: class source: Symfony\Component\Form\Exception\TransformationFailedException - name: TextType type: class source: Symfony\Component\Form\Extension\Core\Type\TextType - name: FormUtil type: class source: Symfony\Component\Form\Util\FormUtil - name: InheritDataAwareIterator type: class source: Symfony\Component\Form\Util\InheritDataAwareIterator - name: OrderedHashMap type: class source: Symfony\Component\Form\Util\OrderedHashMap - name: PropertyPath type: class source: Symfony\Component\PropertyAccess\PropertyPath - name: PropertyPathInterface type: class source: Symfony\Component\PropertyAccess\PropertyPathInterface properties: [] methods: - name: __construct visibility: public parameters: - name: config comment: "# * Form represents a form.\n# *\n# * To implement your own form fields,\ \ you need to have a thorough understanding\n# * of the data flow within a form.\ \ A form stores its data in three different\n# * representations:\n# *\n# * \ \ (1) the \"model\" format required by the form's object\n# * (2) the \"normalized\"\ \ format for internal processing\n# * (3) the \"view\" format used for display\ \ simple fields\n# * or map children model data for compound fields\n# *\n\ # * A date field, for example, may store a date as \"Y-m-d\" string (1) in the\n\ # * object. To facilitate processing in the field, this value is normalized\n\ # * to a DateTime object (2). In the HTML representation of your form, a\n# *\ \ localized string (3) may be presented to and modified by the user, or it could\ \ be an array of values\n# * to be mapped to choices fields.\n# *\n# * In most\ \ cases, format (1) and format (2) will be the same. For example,\n# * a checkbox\ \ field uses a Boolean value for both internal processing and\n# * storage in\ \ the object. In these cases you need to set a view transformer\n# * to convert\ \ between formats (2) and (3). You can do this by calling\n# * addViewTransformer().\n\ # *\n# * In some cases though it makes sense to make format (1) configurable.\ \ To\n# * demonstrate this, let's extend our above date field to store the value\n\ # * either as \"Y-m-d\" string or as timestamp. Internally we still want to\n\ # * use a DateTime object for processing. To convert the data from string/integer\n\ # * to DateTime you can set a model transformer by calling\n# * addModelTransformer().\ \ The normalized data is then converted to the displayed\n# * data as described\ \ before.\n# *\n# * The conversions (1) -> (2) -> (3) use the transform methods\ \ of the transformers.\n# * The conversions (3) -> (2) -> (1) use the reverseTransform\ \ methods of the transformers.\n# *\n# * @author Fabien Potencier \n\ # * @author Bernhard Schussek \n# *\n# * @implements \\IteratorAggregate\n# */\n# class Form implements \\IteratorAggregate, FormInterface,\ \ ClearableErrorsInterface\n# {\n# private ?FormInterface $parent = null;\n# \n\ # /**\n# * A map of FormInterface instances.\n# *\n# * @var OrderedHashMap\n\ # */\n# private OrderedHashMap $children;\n# \n# /**\n# * @var FormError[]\n#\ \ */\n# private array $errors = [];\n# \n# private bool $submitted = false;\n\ # \n# /**\n# * The button that was used to submit the form.\n# */\n# private FormInterface|ClickableInterface|null\ \ $clickedButton = null;\n# \n# private mixed $modelData = null;\n# private mixed\ \ $normData = null;\n# private mixed $viewData = null;\n# \n# /**\n# * The submitted\ \ values that don't belong to any children.\n# */\n# private array $extraData\ \ = [];\n# \n# /**\n# * The transformation failure generated during submission,\ \ if any.\n# */\n# private ?TransformationFailedException $transformationFailure\ \ = null;\n# \n# /**\n# * Whether the form's data has been initialized.\n# *\n\ # * When the data is initialized with its default value, that default value\n\ # * is passed through the transformer chain in order to synchronize the\n# * model,\ \ normalized and view format for the first time. This is done\n# * lazily in order\ \ to save performance when {@link setData()} is called\n# * manually, making the\ \ initialization with the configured default value\n# * superfluous.\n# */\n#\ \ private bool $defaultDataSet = false;\n# \n# /**\n# * Whether setData() is currently\ \ being called.\n# */\n# private bool $lockSetData = false;\n# \n# private string\ \ $name = '';\n# \n# /**\n# * Whether the form inherits its underlying data from\ \ its parent.\n# */\n# private bool $inheritData;\n# \n# private ?PropertyPathInterface\ \ $propertyPath = null;\n# \n# /**\n# * @throws LogicException if a data mapper\ \ is not provided for a compound form" - name: __clone visibility: public parameters: [] comment: null - name: getConfig visibility: public parameters: [] comment: null - name: getName visibility: public parameters: [] comment: null - name: getPropertyPath visibility: public parameters: [] comment: null - name: isRequired visibility: public parameters: [] comment: null - name: isDisabled visibility: public parameters: [] comment: null - name: setParent visibility: public parameters: - name: parent comment: null - name: getParent visibility: public parameters: [] comment: null - name: getRoot visibility: public parameters: [] comment: null - name: isRoot visibility: public parameters: [] comment: null - name: setData visibility: public parameters: - name: modelData comment: null - name: getData visibility: public parameters: [] comment: null - name: getNormData visibility: public parameters: [] comment: null - name: getViewData visibility: public parameters: [] comment: null - name: getExtraData visibility: public parameters: [] comment: null - name: initialize visibility: public parameters: [] comment: null - name: handleRequest visibility: public parameters: - name: request default: 'null' comment: null - name: submit visibility: public parameters: - name: submittedData - name: clearMissing default: 'true' comment: null - name: addError visibility: public parameters: - name: error comment: null - name: isSubmitted visibility: public parameters: [] comment: null - name: isSynchronized visibility: public parameters: [] comment: null - name: getTransformationFailure visibility: public parameters: [] comment: null - name: isEmpty visibility: public parameters: [] comment: null - name: isValid visibility: public parameters: [] comment: null - name: getClickedButton visibility: public parameters: [] comment: '# * Returns the button that was used to submit the form.' - name: getErrors visibility: public parameters: - name: deep default: 'false' - name: flatten default: 'true' comment: null - name: offsetExists visibility: public parameters: - name: name comment: "# @var FormInterface $child */\n# if ($child->isSubmitted() && $child->isValid())\ \ {\n# continue;\n# }\n# \n# $iterator = $child->getErrors(true, $flatten);\n\ # \n# if (0 === \\count($iterator)) {\n# continue;\n# }\n# \n# if ($flatten) {\n\ # foreach ($iterator as $error) {\n# $errors[] = $error;\n# }\n# } else {\n# $errors[]\ \ = $iterator;\n# }\n# }\n# }\n# \n# return new FormErrorIterator($this, $errors);\n\ # }\n# \n# public function clearErrors(bool $deep = false): static\n# {\n# $this->errors\ \ = [];\n# \n# if ($deep) {\n# // Clear errors from children\n# foreach ($this\ \ as $child) {\n# if ($child instanceof ClearableErrorsInterface) {\n# $child->clearErrors(true);\n\ # }\n# }\n# }\n# \n# return $this;\n# }\n# \n# public function all(): array\n\ # {\n# return iterator_to_array($this->children);\n# }\n# \n# public function\ \ add(FormInterface|string $child, ?string $type = null, array $options = []):\ \ static\n# {\n# if ($this->submitted) {\n# throw new AlreadySubmittedException('You\ \ cannot add children to a submitted form.');\n# }\n# \n# if (!$this->config->getCompound())\ \ {\n# throw new LogicException('You cannot add children to a simple form. Maybe\ \ you should set the option \"compound\" to true?');\n# }\n# \n# if (!$child instanceof\ \ FormInterface) {\n# // Never initialize child forms automatically\n# $options['auto_initialize']\ \ = false;\n# \n# if (null === $type && null === $this->config->getDataClass())\ \ {\n# $type = TextType::class;\n# }\n# \n# if (null === $type) {\n# $child =\ \ $this->config->getFormFactory()->createForProperty($this->config->getDataClass(),\ \ $child, null, $options);\n# } else {\n# $child = $this->config->getFormFactory()->createNamed($child,\ \ $type, null, $options);\n# }\n# } elseif ($child->getConfig()->getAutoInitialize())\ \ {\n# 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()));\n# }\n# \n# $this->children[$child->getName()]\ \ = $child;\n# \n# $child->setParent($this);\n# \n# // If setData() is currently\ \ being called, there is no need to call\n# // mapDataToForms() here, as mapDataToForms()\ \ is called at the end\n# // of setData() anyway. Not doing this check leads to\ \ an endless\n# // recursion when initializing the form lazily and an event listener\n\ # // (such as ResizeFormListener) adds fields depending on the data:\n# //\n#\ \ // * setData() is called, the form is not initialized yet\n# // * add() is\ \ called by the listener (setData() is not complete, so\n# // the form is still\ \ not initialized)\n# // * getViewData() is called\n# // * setData() is called\ \ since the form is not initialized yet\n# // * ... endless recursion ...\n#\ \ //\n# // Also skip data mapping if setData() has not been called yet.\n# //\ \ setData() will be called upon form initialization and data mapping\n# // will\ \ take place by then.\n# if (!$this->lockSetData && $this->defaultDataSet && !$this->inheritData)\ \ {\n# $viewData = $this->getViewData();\n# $this->config->getDataMapper()->mapDataToForms(\n\ # $viewData,\n# new \\RecursiveIteratorIterator(new InheritDataAwareIterator(new\ \ \\ArrayIterator([$child->getName() => $child])))\n# );\n# }\n# \n# return $this;\n\ # }\n# \n# public function remove(string $name): static\n# {\n# if ($this->submitted)\ \ {\n# throw new AlreadySubmittedException('You cannot remove children from a\ \ submitted form.');\n# }\n# \n# if (isset($this->children[$name])) {\n# if (!$this->children[$name]->isSubmitted())\ \ {\n# $this->children[$name]->setParent(null);\n# }\n# \n# unset($this->children[$name]);\n\ # }\n# \n# return $this;\n# }\n# \n# public function has(string $name): bool\n\ # {\n# return isset($this->children[$name]);\n# }\n# \n# public function get(string\ \ $name): FormInterface\n# {\n# if (isset($this->children[$name])) {\n# return\ \ $this->children[$name];\n# }\n# \n# throw new OutOfBoundsException(\\sprintf('Child\ \ \"%s\" does not exist.', $name));\n# }\n# \n# /**\n# * Returns whether a child\ \ with the given name exists (implements the \\ArrayAccess interface).\n# *\n\ # * @param string $name The name of the child" - name: offsetGet visibility: public parameters: - name: name comment: '# * Returns the child with the given name (implements the \ArrayAccess interface). # * # * @param string $name The name of the child # * # * @throws OutOfBoundsException if the named child does not exist' - name: offsetSet visibility: public parameters: - name: name - name: child comment: '# * Adds a child to the form (implements the \ArrayAccess interface). # * # * @param string $name Ignored. The name of the child is used # * @param FormInterface $child The child to be added # * # * @throws AlreadySubmittedException if the form has already been submitted # * @throws LogicException when trying to add a child to a non-compound form # * # * @see self::add()' - name: offsetUnset visibility: public parameters: - name: name comment: '# * Removes the child with the given name from the form (implements the \ArrayAccess interface). # * # * @param string $name The name of the child to remove # * # * @throws AlreadySubmittedException if the form has already been submitted' - name: getIterator visibility: public parameters: [] comment: '# * Returns the iterator for this group. # * # * @return \Traversable' - name: count visibility: public parameters: [] comment: '# * Returns the number of form children (implements the \Countable interface).' - name: createView visibility: public parameters: - name: parent default: 'null' comment: null - name: sort visibility: private parameters: - name: '&$children' comment: '# * Sorts view fields based on their priority value.' - name: modelToNorm visibility: private parameters: - name: value comment: '# * Normalizes the underlying data if a model transformer is set. # * # * @throws TransformationFailedException If the underlying data cannot be transformed to "normalized" format' - name: normToModel visibility: private parameters: - name: value comment: '# * Reverse transforms a value if a model transformer is set. # * # * @throws TransformationFailedException If the value cannot be transformed to "model" format' - name: normToView visibility: private parameters: - name: value comment: '# * Transforms the value if a view transformer is set. # * # * @throws TransformationFailedException If the normalized value cannot be transformed to "view" format' - name: viewToNorm visibility: private parameters: - name: value comment: '# * Reverse transforms a value if a view transformer is set. # * # * @throws TransformationFailedException If the submitted value cannot be transformed to "normalized" format' traits: - Symfony\Component\Form\Event\PostSetDataEvent - Symfony\Component\Form\Event\PostSubmitEvent - Symfony\Component\Form\Event\PreSetDataEvent - Symfony\Component\Form\Event\PreSubmitEvent - Symfony\Component\Form\Event\SubmitEvent - Symfony\Component\Form\Exception\AlreadySubmittedException - Symfony\Component\Form\Exception\LogicException - Symfony\Component\Form\Exception\OutOfBoundsException - Symfony\Component\Form\Exception\RuntimeException - Symfony\Component\Form\Exception\TransformationFailedException - Symfony\Component\Form\Extension\Core\Type\TextType - Symfony\Component\Form\Util\FormUtil - Symfony\Component\Form\Util\InheritDataAwareIterator - Symfony\Component\Form\Util\OrderedHashMap - Symfony\Component\PropertyAccess\PropertyPath - Symfony\Component\PropertyAccess\PropertyPathInterface interfaces: - \IteratorAggregate - \IteratorAggregate - the - the - the - the - the