Symfony2 API
Class

Symfony\Component\Form\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.

bind($submittedData)

Alias of {@link submit()}.

FormInterface addError(FormError $error)

Adds an error to this form.

bool isSubmitted()

Returns whether the form is submitted.

isBound()

Alias of {@link isSubmitted()}.

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.

string getErrorsAsString(int $level)

Returns a string representation of all form errors (including children errors).

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

at line 156
public __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

at line 175
public __clone()

at line 187
public FormConfigInterface getConfig()

Returns the form's configuration.

Return Value

FormConfigInterface The configuration.

at line 195
public string getName()

Returns the name by which the form is identified in forms.

Return Value

string The name of the form.

at line 203
public PropertyPathInterface getPropertyPath()

Returns the property path that the form is mapped to.

Return Value

PropertyPathInterface The property path.

at line 229
public 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

at line 241
public 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

at line 253
public 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.

at line 271
public FormInterface|null getParent()

Returns the parent form.

Return Value

FormInterface|null The parent form or null if there is none.

at line 279
public FormInterface getRoot()

Returns the root of the form tree.

Return Value

FormInterface The root of the tree

at line 287
public bool isRoot()

Returns whether the field is the root of the form tree.

Return Value

bool

at line 295
public 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}.

at line 397
public mixed getData()

Returns the data in the format needed for the underlying object.

Return Value

mixed

at line 417
public 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.

at line 437
public mixed getViewData()

Returns the data transformed by the value transformer.

Return Value

mixed

at line 457
public array getExtraData()

Returns the extra data.

Return Value

array The submitted data which do not belong to a child

at line 465
public FormInterface initialize()

Initializes the form tree.

Should be called on the root form after constructing the tree.

Return Value

FormInterface The form instance.

at line 484
public 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.

at line 494
public 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.

at line 665
public bind($submittedData)

Alias of {@link submit()}.

Parameters

$submittedData

at line 673
public FormInterface addError(FormError $error)

Adds an error to this form.

Parameters

FormError $error

Return Value

FormInterface The form instance

at line 691
public bool isSubmitted()

Returns whether the form is submitted.

Return Value

bool true if the form is submitted, false otherwise

at line 702
public isBound()

Alias of {@link isSubmitted()}.

at line 710
public 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

at line 718
public TransformationFailedException|null getTransformationFailure()

Returns the data transformation failure, if any.

Return Value

TransformationFailedException|null The transformation failure

at line 726
public bool isEmpty()

Returns whether the form is empty.

Return Value

bool

at line 744
public 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

at line 767
public 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

at line 781
public 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

at line 824
public string getErrorsAsString(int $level)

Returns a string representation of all form errors (including children errors).

This method should only be used to help debug a form.

Parameters

int $level The indentation level (used internally)

Return Value

string A string representation of all errors

at line 834
public FormInterface[] all()

Returns all children in this group.

Return Value

FormInterface[] An array of FormInterface instances

at line 842
public 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.

at line 916
public 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.

at line 936
public bool has(string $name)

Returns whether a child with the given name exists.

Parameters

string $name The name of the child

Return Value

bool

at line 944
public 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.

at line 960
public 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

at line 974
public 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.

at line 990
public 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()

at line 1002
public 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.

at line 1012
public Traversable getIterator()

Returns the iterator for this group.

Return Value

Traversable

at line 1022
public int count()

Returns the number of form children (implements the \Countable interface).

Return Value

int The number of embedded form children

at line 1030
public FormView createView(FormView $parent = null)

Creates a view.

Parameters

FormView $parent The parent view

Return Value

FormView The view