Class

Symfony\Component\Form\Form

class Form implements IteratorAggregate, FormInterface

Form represents a form.

A form is composed of a validator schema and a widget form schema.

To implement your own form fields, you need to have a thorough understanding of the data flow within a form field. A form field stores its data in three different representations:

(1) the format required by the form's object (2) a normalized format for internal processing (3) the 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 both for internal processing as for 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 appendClientTransformer().

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 appendNormTransformer(). The normalized data is then converted to the displayed data as described before.

Methods

__construct($name, EventDispatcherInterface $dispatcher, array $types = array(), array $clientTransformers = array(), array $normTransformers = array(), DataMapperInterface $dataMapper = null, array $validators = array(), $required = false, $readOnly = false, $errorBubbling = false, $emptyData = null, array $attributes = array())

__clone()

string getName()

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

array getTypes()

Returns the types used by this form.

Boolean isRequired()

Returns whether the form is required to be filled out.

Boolean isReadOnly()

Returns whether this form is read only.

Form setParent(FormInterface $parent = null)

Sets the parent form.

FormInterface getParent()

Returns the parent field.

Boolean hasParent()

Returns whether the form has a parent.

FormInterface getRoot()

Returns the root of the form tree.

Boolean isRoot()

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

Boolean hasAttribute(string $name)

Returns whether the form has an attribute with the given name.

getAttribute(string $name)

Returns the value of the attributes with the given name.

Form setData(array $appData)

Updates the field with default data.

mixed getData()

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

string getClientData()

Returns the data transformed by the value transformer.

array getExtraData()

Returns the extra data.

Form bind(string|array $clientData)

Binds data to the field, transforms and validates it.

Form bindRequest(Request $request)

Binds a request to the form.

mixed getNormData()

Returns the normalized data of the field.

Form addError(FormError $error)

Adds an error to this form.

Boolean getErrorBubbling()

Returns whether errors bubble up to the parent.

Boolean isBound()

Returns whether the field is bound.

Boolean isSynchronized()

Returns whether the data in the different formats is synchronized.

Boolean isEmpty()

Returns whether the form is empty.

Boolean isValid()

Returns whether the field is valid.

Boolean hasErrors()

Returns whether or not there are errors.

array getErrors()

Returns all errors.

array getNormTransformers()

Returns the DataTransformers.

array getClientTransformers()

Returns the DataTransformers.

array getChildren()

Returns all children in this group.

Boolean hasChildren()

Return whether the form has children.

Form add(FormInterface $child)

Adds a child to the form.

Form remove(string $name)

Removes a child from the form.

Boolean has(string $name)

Returns whether a child with the given name exists.

FormInterface get(string $name)

Returns the child with the given name.

Boolean offsetExists(string $name)

Returns true if the child exists (implements the \ArrayAccess interface).

FormInterface offsetGet(string $name)

Returns the form child associated with the 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).

ArrayIterator getIterator()

Returns the iterator for this group.

integer count()

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

FormView createView(FormView $parent = null)

Creates a view.

Details

at line 189
public __construct($name, EventDispatcherInterface $dispatcher, array $types = array(), array $clientTransformers = array(), array $normTransformers = array(), DataMapperInterface $dataMapper = null, array $validators = array(), $required = false, $readOnly = false, $errorBubbling = false, $emptyData = null, array $attributes = array())

Parameters

$name
EventDispatcherInterface $dispatcher
array $types
array $clientTransformers
array $normTransformers
DataMapperInterface $dataMapper
array $validators
$required
$readOnly
$errorBubbling
$emptyData
array $attributes

at line 230
public __clone()

at line 242
public string getName()

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

Return Value

string The name of the form.

at line 252
public array getTypes()

Returns the types used by this form.

Return Value

array An array of FormTypeInterface

at line 266
public Boolean 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

Boolean

at line 286
public Boolean isReadOnly()

Returns whether this form is read only.

The content of a read-only form is displayed, but not allowed to be modified. The validation of modified read-only forms should fail.

Fields whose parents are read-only are considered read-only regardless of their own state.

Return Value

Boolean

at line 302
public Form setParent(FormInterface $parent = null)

Sets the parent form.

Parameters

FormInterface $parent The parent form

Return Value

Form The current form

at line 314
public FormInterface getParent()

Returns the parent field.

Return Value

FormInterface The parent field

at line 324
public Boolean hasParent()

Returns whether the form has a parent.

Return Value

Boolean

at line 334
public FormInterface getRoot()

Returns the root of the form tree.

Return Value

FormInterface The root of the tree

at line 344
public Boolean isRoot()

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

Return Value

Boolean

at line 356
public Boolean hasAttribute(string $name)

Returns whether the form has an attribute with the given name.

Parameters

string $name The name of the attribute

Return Value

Boolean

at line 366
public getAttribute(string $name)

Returns the value of the attributes with the given name.

Parameters

string $name The name of the attribute

at line 378
public Form setData(array $appData)

Updates the field with default data.

Parameters

array $appData The data formatted as expected for the underlying object

Return Value

Form The current form

at line 418
public mixed getData()

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

Return Value

mixed

at line 428
public string getClientData()

Returns the data transformed by the value transformer.

Return Value

string

at line 438
public array getExtraData()

Returns the extra data.

Return Value

array The bound data which do not belong to a child

at line 452
public Form bind(string|array $clientData)

Binds data to the field, transforms and validates it.

Parameters

string|array $clientData The data

Return Value

Form The current form

Exceptions

UnexpectedTypeException

at line 572
public Form bindRequest(Request $request)

Binds a request to the form.

If the request method is POST, PUT or GET, the data is bound to the form, transformed and written into the form data (an object or an array).

Parameters

Request $request The request to bind to the form

Return Value

Form This form

Exceptions

FormException if the method of the request is not one of GET, POST or PUT

at line 600
public mixed getNormData()

Returns the normalized data of the field.

Return Value

mixed When the field is not bound, the default data is returned. When the field is bound, the normalized bound data is returned if the field is valid, null otherwise.

at line 612
public Form addError(FormError $error)

Adds an error to this form.

Parameters

FormError $error

Return Value

Form The current form

at line 628
public Boolean getErrorBubbling()

Returns whether errors bubble up to the parent.

Return Value

Boolean

at line 638
public Boolean isBound()

Returns whether the field is bound.

Return Value

Boolean true if the form is bound to input values, false otherwise

at line 648
public Boolean isSynchronized()

Returns whether the data in the different formats is synchronized.

Return Value

Boolean

at line 658
public Boolean isEmpty()

Returns whether the form is empty.

Return Value

Boolean

at line 674
public Boolean isValid()

Returns whether the field is valid.

Return Value

Boolean

at line 700
public Boolean hasErrors()

Returns whether or not there are errors.

Return Value

Boolean true if form is bound and not valid

at line 714
public array getErrors()

Returns all errors.

Return Value

array An array of FormError instances that occurred during binding

at line 724
public array getNormTransformers()

Returns the DataTransformers.

Return Value

array An array of DataTransformerInterface

at line 734
public array getClientTransformers()

Returns the DataTransformers.

Return Value

array An array of DataTransformerInterface

at line 744
public array getChildren()

Returns all children in this group.

Return Value

array An array of FormInterface instances

at line 754
public Boolean hasChildren()

Return whether the form has children.

Return Value

Boolean

at line 766
public Form add(FormInterface $child)

Adds a child to the form.

Parameters

FormInterface $child The FormInterface to add as a child

Return Value

Form the current form

at line 786
public Form remove(string $name)

Removes a child from the form.

Parameters

string $name The name of the child to remove

Return Value

Form the current form

at line 804
public Boolean has(string $name)

Returns whether a child with the given name exists.

Parameters

string $name

Return Value

Boolean

at line 818
public FormInterface get(string $name)

Returns the child with the given name.

Parameters

string $name

Return Value

FormInterface

Exceptions

InvalidArgumentException if the child does not exist

at line 834
public Boolean offsetExists(string $name)

Returns true if the child exists (implements the \ArrayAccess interface).

Parameters

string $name The name of the child

Return Value

Boolean true if the widget exists, false otherwise

at line 846
public FormInterface offsetGet(string $name)

Returns the form child associated with the name (implements the \ArrayAccess interface).

Parameters

string $name The offset of the value to get

Return Value

FormInterface A form instance

at line 857
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

at line 867
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 be removed

at line 877
public ArrayIterator getIterator()

Returns the iterator for this group.

Return Value

ArrayIterator

at line 887
public integer count()

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

Return Value

integer The number of embedded form children

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

Creates a view.

Parameters

FormView $parent The parent view

Return Value

FormView The view