Form
class Form implements IteratorAggregate, FormInterface, ClearableErrorsInterface
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 simply 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.
Methods
No description
Returns the form's configuration.
Returns the name by which the form is identified in forms.
Returns the property path that the form is mapped to.
Returns whether the form is required to be filled out.
Returns whether this form is disabled.
Returns the parent form.
Returns the root of the form tree.
Returns whether the field is the root of the form tree.
Updates the form with default data.
Returns the data in the format needed for the underlying object.
Returns the normalized data of the field.
Returns the data transformed by the value transformer.
Returns the extra data.
Initializes the form tree.
Inspects the given request and calls {@link submit()} if the form was submitted.
Submits data to the form, transforms and validates it.
Returns whether the form is submitted.
Returns whether the data in the different formats is synchronized.
Returns the data transformation failure, if any.
Returns whether the form is empty.
Returns whether the form and all children are valid.
Returns the button that was used to submit the form.
Returns the errors of this form.
Removes all the errors of this form.
Returns all children in this group.
Adds or replaces a child to the form.
Removes a child from the form.
Returns whether a child with the given name exists.
Returns the child with the given name.
Returns whether a child with the given name exists (implements the \ArrayAccess interface).
Returns the child with the given name (implements the \ArrayAccess interface).
Adds a child to the form (implements the \ArrayAccess interface).
Removes the child with the given name from the form (implements the \ArrayAccess interface).
Returns the iterator for this group.
Returns the number of form children (implements the \Countable interface).
Details
bool
isRequired()
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
isDisabled()
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.
$this
initialize()
Initializes the form tree.
Should be called on the root form after constructing the tree.
$this
handleRequest(mixed $request = null)
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.
$this
submit(mixed $submittedData, bool $clearMissing = true)
Submits data to the form, transforms and validates it.
bool
isSynchronized()
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()}.
TransformationFailedException|null
getTransformationFailure()
Returns the data transformation failure, if any.
FormErrorIterator
getErrors(bool $deep = false, bool $flatten = true)
Returns the errors of this form.
FormInterface
add(FormInterface|string|int $child, string|null $type = null, array $options = array())
Adds or replaces a child to the form.
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).