class Form implements IteratorAggregate, FormInterface
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
A date field, for example, may store a date as "Y-m-d" string (1) in the object. To facilitate processing in the field, this value is normalized to a DateTime object (2). In the HTML representation of your form, a localized string (3) is presented to and modified by the user.
In most cases, format (1) and format (2) will be the same. For example, a checkbox field uses a Boolean value for both internal processing and storage in the object. In these cases you simply need to set a value transformer to convert between formats (2) and (3). You can do this by calling 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 normalization 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.
__construct(FormConfigInterface $config) Creates a new form based on the given configuration. | ||
__clone() | ||
FormConfigInterface | getConfig() Returns the form's configuration. | |
string | getName() Returns the name by which the form is identified in forms. | |
PropertyPathInterface|null | getPropertyPath() Returns the property path that the form is mapped to. | |
bool | isRequired() Returns whether the form is required to be filled out. | |
bool | isDisabled() Returns whether this form is disabled. | |
FormInterface | setParent(FormInterface $parent = null) Sets the parent form. | |
FormInterface|null | getParent() Returns the parent form. | |
FormInterface | getRoot() Returns the root of the form tree. | |
bool | isRoot() Returns whether the field is the root of the form tree. | |
$this | setData(mixed $modelData) Updates the form with default data. | |
mixed | getData() Returns the data in the format needed for the underlying object. | |
mixed | getNormData() Returns the normalized data of the field. | |
mixed | getViewData() Returns the data transformed by the value transformer. | |
array | getExtraData() Returns the extra data. | |
$this | initialize() Initializes the form tree. | |
$this | handleRequest(mixed $request = null) Inspects the given request and calls {@link submit()} if the form was submitted. | |
$this | submit(mixed $submittedData, bool $clearMissing = true) Submits data to the form, transforms and validates it. | |
$this | addError(FormError $error) Adds an error to this form. | |
bool | isSubmitted() Returns whether the form is submitted. | |
bool | isSynchronized() Returns whether the data in the different formats is synchronized. | |
TransformationFailedException|null | getTransformationFailure() Returns the data transformation failure, if any. | |
bool | isEmpty() Returns whether the form is empty. | |
bool | isValid() Returns whether the form and all children are valid. | |
Button|null | getClickedButton() Returns the button that was used to submit the form. | |
FormErrorIterator | getErrors(bool $deep = false, bool $flatten = true) Returns the errors of this form. | |
FormInterface[] | all() Returns all children in this group. | |
FormInterface | add(FormInterface|string|int $child, string|null $type = null, array $options = array()) Adds or replaces a child to the form. | |
$this | remove(string $name) Removes a child from the form. | |
bool | has(string $name) Returns whether a child with the given name exists. | |
FormInterface | get(string $name) Returns the child with the given name. | |
bool | offsetExists(string $name) Returns whether a child with the given name exists (implements the \ArrayAccess interface). | |
FormInterface | offsetGet(string $name) Returns the child with the given name (implements the \ArrayAccess interface). | |
offsetSet(string $name, FormInterface $child) Adds a child to the form (implements the \ArrayAccess interface). | ||
offsetUnset(string $name) Removes the child with the given name from the form (implements the \ArrayAccess interface). | ||
Traversable|FormInterface[] | getIterator() Returns the iterator for this group. | |
int | count() Returns the number of form children (implements the \Countable interface). | |
FormView | createView(FormView $parent = null) Creates a view. |
Creates a new form based on the given configuration.
FormConfigInterface | $config |
LogicException | if a data mapper is not provided for a compound form |
Returns the form's configuration.
FormConfigInterface | The configuration |
Returns the name by which the form is identified in forms.
string | The name of the form |
Returns the property path that the form is mapped to.
PropertyPathInterface|null | The property path |
Returns whether the form is required to be filled out.
If the form has a parent and the parent is not required, this method will always return false. Otherwise the value set with setRequired() is returned.
bool |
Returns whether this form is disabled.
The content of a disabled form is displayed, but not allowed to be modified. The validation of modified disabled forms should fail.
Forms whose parents are disabled are considered disabled regardless of their own state.
bool |
Sets the parent form.
FormInterface | $parent |
FormInterface |
AlreadySubmittedException | if the form has already been submitted |
LogicException | when trying to set a parent for a form with an empty name |
Returns the parent form.
FormInterface|null | The parent form or null if there is none |
Returns the root of the form tree.
FormInterface | The root of the tree |
Returns whether the field is the root of the form tree.
bool |
Updates the form with default data.
mixed | $modelData | The data formatted as expected for the underlying object |
$this |
AlreadySubmittedException | if the form has already been submitted |
LogicException | If listeners try to call setData in a cycle. Or if the view data does not match the expected type according to {@link FormConfigInterface::getDataClass}. |
Returns the data in the format needed for the underlying object.
mixed |
Returns the normalized data of the field.
mixed | when the field is not submitted, the default data is returned. When the field is submitted, the normalized submitted data is returned if the field is valid, null otherwise |
Returns the data transformed by the value transformer.
mixed |
Returns the extra data.
array | The submitted data which do not belong to a child |
Initializes the form tree.
Should be called on the root form after constructing the tree.
$this |
Inspects the given request and calls {@link submit()} if the form was submitted.
Internally, the request is forwarded to the configured {@link RequestHandlerInterface} instance, which determines whether to submit the form or not.
mixed | $request | The request to handle |
$this |
Submits data to the form, transforms and validates it.
mixed | $submittedData | The submitted data |
bool | $clearMissing | Whether to set fields to NULL when they are missing in the submitted data |
$this |
AlreadySubmittedException | if the form has already been submitted |
Adds an error to this form.
FormError | $error |
$this |
Returns whether the form is submitted.
bool | true if the form is submitted, false otherwise |
Returns whether the data in the different formats is synchronized.
If the data is not synchronized, you can get the transformation failure by calling {@link getTransformationFailure()}.
bool |
Returns the data transformation failure, if any.
TransformationFailedException|null | The transformation failure |
Returns whether the form is empty.
bool |
Returns whether the form and all children are valid.
bool |
LogicException | if the form is not submitted |
Returns the button that was used to submit the form.
Button|null | The clicked button or NULL if the form was not submitted |
Returns the errors of this form.
bool | $deep | Whether to include errors of child forms as well |
bool | $flatten | Whether to flatten the list of errors in case $deep is set to true |
FormErrorIterator | An iterator over the {@link FormError} instances that where added to this form |
Returns all children in this group.
FormInterface[] |
Adds or replaces a child to the form.
FormInterface|string|int | $child | The FormInterface instance or the name of the child |
string|null | $type | The child's type, if a name was passed |
array | $options | The child's options, if a name was passed |
FormInterface |
AlreadySubmittedException | if the form has already been submitted |
LogicException | when trying to add a child to a non-compound form |
UnexpectedTypeException | if $child or $type has an unexpected type |
Removes a child from the form.
string | $name | The name of the child to remove |
$this |
AlreadySubmittedException | if the form has already been submitted |
Returns whether a child with the given name exists.
string | $name | The name of the child |
bool |
Returns the child with the given name.
string | $name | The name of the child |
FormInterface |
OutOfBoundsException | if the named child does not exist |
Returns whether a child with the given name exists (implements the \ArrayAccess interface).
string | $name | The name of the child |
bool |
Returns the child with the given name (implements the \ArrayAccess interface).
string | $name | The name of the child |
FormInterface | The child form |
OutOfBoundsException | if the named child does not exist |
Adds a child to the form (implements the \ArrayAccess interface).
string | $name | Ignored. The name of the child is used |
FormInterface | $child | The child to be added |
AlreadySubmittedException | if the form has already been submitted |
LogicException | when trying to add a child to a non-compound form |
Form::add |
Removes the child with the given name from the form (implements the \ArrayAccess interface).
string | $name | The name of the child to remove |
AlreadySubmittedException | if the form has already been submitted |
Returns the iterator for this group.
Traversable|FormInterface[] |
Returns the number of form children (implements the \Countable interface).
int | The number of embedded form children |
Creates a view.
FormView | $parent |
FormView | The view |
© 2004–2017 Fabien Potencier
Licensed under the MIT License.
https://api.symfony.com/4.1/Symfony/Component/Form/Form.html