Form
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 | 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.
Parameters
| FormConfigInterface | $config | The form configuration. |
Exceptions
| LogicException | if a data mapper is not provided for a compound form |
__clone()
FormConfigInterface getConfig()
Returns the form's configuration.
Return Value
| FormConfigInterface | The configuration. |
string getName()
Returns the name by which the form is identified in forms.
Return Value
| string | The name of the form. |
PropertyPathInterface getPropertyPath()
Returns the property path that the form is mapped to.
Return Value
| PropertyPathInterface | The property path. |
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.
Return Value
| bool |
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.
Return Value
| bool |
FormInterface setParent(FormInterface $parent = null)
Sets the parent form.
Parameters
| FormInterface | $parent | The parent form or null if it's the root. |
Return Value
| FormInterface | The form instance |
Exceptions
| AlreadySubmittedException | If the form has already been submitted. |
| LogicException | When trying to set a parent for a form with an empty name. |
FormInterface|null getParent()
Returns the parent form.
Return Value
| FormInterface|null | The parent form or null if there is none. |
FormInterface getRoot()
Returns the root of the form tree.
Return Value
| FormInterface | The root of the tree |
bool isRoot()
Returns whether the field is the root of the form tree.
Return Value
| bool |
FormInterface setData(mixed $modelData)
Updates the form with default data.
Parameters
| mixed | $modelData | The data formatted as expected for the underlying object |
Return Value
| FormInterface | The form instance |
Exceptions
| 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}. |
mixed getData()
Returns the data in the format needed for the underlying object.
Return Value
| mixed |
mixed getNormData()
Returns the normalized data of the field.
Return Value
| 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. |
mixed getViewData()
Returns the data transformed by the value transformer.
Return Value
| mixed |
array getExtraData()
Returns the extra data.
Return Value
| array | The submitted data which do not belong to a child |
FormInterface initialize()
Initializes the form tree.
Should be called on the root form after constructing the tree.
Return Value
| FormInterface | The form instance. |
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.
Parameters
| mixed | $request | The request to handle. |
Return Value
| FormInterface | The form instance. |
FormInterface submit(null|string|array $submittedData, bool $clearMissing = true)
Submits data to the form, transforms and validates it.
Parameters
| null|string|array | $submittedData | The submitted data. |
| bool | $clearMissing | Whether to set fields to NULL when they are missing in the submitted data. |
Return Value
| FormInterface | The form instance |
Exceptions
| AlreadySubmittedException | If the form has already been submitted. |
FormInterface addError(FormError $error)
Adds an error to this form.
Parameters
| FormError | $error |
Return Value
| FormInterface | The form instance |
bool isSubmitted()
Returns whether the form is submitted.
Return Value
| bool | true if the form is submitted, false otherwise |
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()}.
Return Value
| bool |
TransformationFailedException|null getTransformationFailure()
Returns the data transformation failure, if any.
Return Value
| TransformationFailedException|null | The transformation failure |
bool isEmpty()
Returns whether the form is empty.
Return Value
| bool |
bool isValid()
Returns whether the form and all children are valid.
If the form is not submitted, this method always returns false.
Return Value
| bool |
Button|null getClickedButton()
Returns the button that was used to submit the form.
Return Value
| Button|null | The clicked button or NULL if the form was not submitted |
FormErrorIterator getErrors(bool $deep = false, bool $flatten = true)
Returns the errors of this form.
Parameters
| 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 |
Return Value
| FormErrorIterator | An iterator over the {@link FormError} instances that where added to this form |
FormInterface[] all()
Returns all children in this group.
Return Value
| FormInterface[] | An array of FormInterface instances |
FormInterface add(FormInterface|string|int $child, string|null $type = null, array $options = array())
Adds or replaces a child to the form.
Parameters
| 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. |
Return Value
| FormInterface | The form instance |
Exceptions
| 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. |
FormInterface remove(string $name)
Removes a child from the form.
Parameters
| string | $name | The name of the child to remove |
Return Value
| FormInterface | The form instance |
Exceptions
| AlreadySubmittedException | If the form has already been submitted. |
bool has(string $name)
Returns whether a child with the given name exists.
Parameters
| string | $name | The name of the child |
Return Value
| bool |
FormInterface get(string $name)
Returns the child with the given name.
Parameters
| string | $name | The name of the child |
Return Value
| FormInterface | The child form |
Exceptions
| OutOfBoundsException | If the named child does not exist. |
bool offsetExists(string $name)
Returns whether a child with the given name exists (implements the \ArrayAccess interface).
Parameters
| string | $name | The name of the child |
Return Value
| bool |
FormInterface offsetGet(string $name)
Returns the child with the given name (implements the \ArrayAccess interface).
Parameters
| string | $name | The name of the child |
Return Value
| FormInterface | The child form |
Exceptions
| OutOfBoundsException | If the named child does not exist. |
offsetSet(string $name, FormInterface $child)
Adds a child to the form (implements the \ArrayAccess interface).
Parameters
| string | $name | Ignored. The name of the child is used. |
| FormInterface | $child | The child to be added. |
Exceptions
| AlreadySubmittedException | If the form has already been submitted. |
| LogicException | When trying to add a child to a non-compound form. |
See also
| self::add() |
offsetUnset(string $name)
Removes the child with the given name from the form (implements the \ArrayAccess interface).
Parameters
| string | $name | The name of the child to remove |
Exceptions
| AlreadySubmittedException | If the form has already been submitted. |
Traversable getIterator()
Returns the iterator for this group.
Return Value
| Traversable |
int count()
Returns the number of form children (implements the \Countable interface).
Return Value
| int | The number of embedded form children |
FormView createView(FormView $parent = null)
Creates a view.
Parameters
| FormView | $parent | The parent view |
Return Value
| FormView | The view |
© 2004–2017 Fabien Potencier
Licensed under the MIT License.
http://api.symfony.com/3.0/Symfony/Component/Form/Form.html