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 addNormTransformer(). 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
| __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 | 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. | |
| FormInterface | 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. | |
| FormInterface | initialize() Initializes the form tree. | |
| FormInterface | handleRequest(mixed $request = null) Inspects the given request and calls {@link submit()} if the form was submitted. | |
| FormInterface | submit(null|string|array $submittedData, bool $clearMissing = true) Submits data to the form, transforms and validates it. | |
| FormInterface | 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. | |
| FormInterface | 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. |
Details
__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 getPropertyPath()
Returns the property path that the form is mapped to.
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.
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.
FormInterface 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.
FormInterface initialize()
Initializes the form tree.
Should be called on the root form after constructing the tree.
FormInterface 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.
FormInterface submit(null|string|array $submittedData, bool $clearMissing = true)
Submits data to the form, transforms and validates it.
FormInterface 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.
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.
bool isEmpty()
Returns whether the form is empty.
bool isValid()
Returns whether the form and all children are valid.
If the form is not submitted, this method always returns false.
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.
FormInterface 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).
Please login to continue.