Documentation

Form
in package
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 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.

Tags
author

Fabien Potencier fabien@symfony.com

author

Bernhard Schussek bschussek@gmail.com

implements

\IteratorAggregate<string, FormInterface>

Table of Contents

Interfaces

IteratorAggregate
FormInterface
A form group bundling multiple forms in a hierarchical structure.
ClearableErrorsInterface
A form element whose errors can be cleared.

Properties

$children  : OrderedHashMap<string, FormInterface>
A map of FormInterface instances.
$clickedButton  : mixed
The button that was used to submit the form.
$config  : mixed
$defaultDataSet  : bool
Whether the form's data has been initialized.
$errors  : array<string|int, FormError>
$extraData  : array<string|int, mixed>
The submitted values that don't belong to any children.
$inheritData  : bool
Whether the form inherits its underlying data from its parent.
$lockSetData  : bool
Whether setData() is currently being called.
$modelData  : mixed
$name  : string
$normData  : mixed
$parent  : mixed
$propertyPath  : mixed
$submitted  : bool
$transformationFailure  : mixed
The transformation failure generated during submission, if any.
$viewData  : mixed

Methods

__clone()  : mixed
__construct()  : mixed
add()  : $this
Adds or replaces a child to the form.
addError()  : $this
Adds an error to this form.
all()  : array<string|int, self>
Returns all children in this group.
clearErrors()  : $this
Removes all the errors of this form.
count()  : int
Returns the number of form children (implements the \Countable interface).
createView()  : FormView
get()  : FormInterface
Returns the child with the given name.
getClickedButton()  : FormInterface|ClickableInterface|null
Returns the button that was used to submit the form.
getConfig()  : FormConfigInterface
Returns the form's configuration.
getData()  : mixed
Returns the model data in the format needed for the underlying object.
getErrors()  : FormErrorIterator
Returns the errors of this form.
getExtraData()  : array<string|int, mixed>
Returns the extra submitted data.
getIterator()  : Traversable<string, FormInterface>
Returns the iterator for this group.
getName()  : string
Returns the name by which the form is identified in forms.
getNormData()  : mixed
Returns the normalized data of the field, used as internal bridge between model data and view data.
getParent()  : FormInterface|null
Returns the parent form.
getPropertyPath()  : PropertyPathInterface|null
Returns the property path that the form is mapped to.
getRoot()  : FormInterface
Returns the root of the form tree.
getTransformationFailure()  : TransformationFailedException|null
Returns the data transformation failure, if any, during submission.
getViewData()  : mixed
Returns the view data of the field.
handleRequest()  : $this
Inspects the given request and calls {@link submit()} if the form was submitted.
has()  : bool
Returns whether a child with the given name exists.
initialize()  : $this
Initializes the form tree.
isDisabled()  : bool
Returns whether this form is disabled.
isEmpty()  : bool
Returns whether the form is empty.
isRequired()  : bool
Returns whether the form is required to be filled out.
isRoot()  : bool
Returns whether the field is the root of the form tree.
isSubmitted()  : bool
Returns whether the form is submitted.
isSynchronized()  : bool
Returns whether the data in the different formats is synchronized.
isValid()  : bool
Returns whether the form and all children are valid.
offsetExists()  : bool
Returns whether a child with the given name exists (implements the \ArrayAccess interface).
offsetGet()  : FormInterface
Returns the child with the given name (implements the \ArrayAccess interface).
offsetSet()  : void
Adds a child to the form (implements the \ArrayAccess interface).
offsetUnset()  : void
Removes the child with the given name from the form (implements the \ArrayAccess interface).
remove()  : $this
Removes a child from the form.
setData()  : $this
Updates the form with default model data.
setParent()  : $this
Sets the parent form.
submit()  : $this
Submits data to the form.
modelToNorm()  : mixed
Normalizes the underlying data if a model transformer is set.
normToModel()  : mixed
Reverse transforms a value if a model transformer is set.
normToView()  : mixed
Transforms the value if a view transformer is set.
sort()  : void
Sorts view fields based on their priority value.
viewToNorm()  : mixed
Reverse transforms a value if a view transformer is set.

Properties

$children

A map of FormInterface instances.

private OrderedHashMap<string, FormInterface> $children

$clickedButton

The button that was used to submit the form.

private mixed $clickedButton = null

$config

private mixed $config

$defaultDataSet

Whether the form's data has been initialized.

private bool $defaultDataSet = false

When the data is initialized with its default value, that default value is passed through the transformer chain in order to synchronize the model, normalized and view format for the first time. This is done lazily in order to save performance when is called manually, making the initialization with the configured default value superfluous.

$extraData

The submitted values that don't belong to any children.

private array<string|int, mixed> $extraData = []

$inheritData

Whether the form inherits its underlying data from its parent.

private bool $inheritData

$lockSetData

Whether setData() is currently being called.

private bool $lockSetData = false

$modelData

private mixed $modelData = null

$name

private string $name = ''

$normData

private mixed $normData = null

$parent

private mixed $parent = null

$propertyPath

private mixed $propertyPath = null

$submitted

private bool $submitted = false

$transformationFailure

The transformation failure generated during submission, if any.

private mixed $transformationFailure = null

$viewData

private mixed $viewData = null

Methods

__clone()

public __clone() : mixed

add()

Adds or replaces a child to the form.

public add(FormInterface|string $child[, string $type = null ][, array<string|int, mixed> $options = [] ]) : $this
Parameters
$child : FormInterface|string

The FormInterface instance or the name of the child

$type : string = null

The child's type, if a name was passed

$options : array<string|int, mixed> = []

The child's options, if a name was passed

Return values
$this

addError()

Adds an error to this form.

public addError(FormError $error) : $this
Parameters
$error : FormError
Return values
$this

all()

Returns all children in this group.

public all() : array<string|int, self>
Return values
array<string|int, self>

clearErrors()

Removes all the errors of this form.

public clearErrors([bool $deep = false ]) : $this
Parameters
$deep : bool = false

Whether to remove errors from child forms as well

Return values
$this

count()

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

public count() : int
Return values
int

getData()

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

public getData() : mixed
Return values
mixed —

When the field is not submitted, the default data is returned. When the field is submitted, the default data has been bound to the submitted view data.

getErrors()

Returns the errors of this form.

public getErrors([bool $deep = false ][, bool $flatten = true ]) : FormErrorIterator
Parameters
$deep : bool = false

Whether to include errors of child forms as well

$flatten : bool = true

Whether to flatten the list of errors in case $deep is set to true

Return values
FormErrorIterator

getExtraData()

Returns the extra submitted data.

public getExtraData() : array<string|int, mixed>
Return values
array<string|int, mixed> —

The submitted data which do not belong to a child

getIterator()

Returns the iterator for this group.

public getIterator() : Traversable<string, FormInterface>
Return values
Traversable<string, FormInterface>

getName()

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

public getName() : string
Return values
string

getNormData()

Returns the normalized data of the field, used as internal bridge between model data and view data.

public getNormData() : mixed
Return values
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 synchronized with the view data, null otherwise.

getViewData()

Returns the view data of the field.

public getViewData() : mixed

handleRequest()

Inspects the given request and calls {@link submit()} if the form was submitted.

public handleRequest([mixed $request = null ]) : $this
Parameters
$request : mixed = null
Return values
$this

has()

Returns whether a child with the given name exists.

public has(string $name) : bool
Parameters
$name : string
Return values
bool

initialize()

Initializes the form tree.

public initialize() : $this
Return values
$this

isDisabled()

Returns whether this form is disabled.

public isDisabled() : bool
Return values
bool

isEmpty()

Returns whether the form is empty.

public isEmpty() : bool
Return values
bool

isRequired()

Returns whether the form is required to be filled out.

public isRequired() : bool
Return values
bool

isRoot()

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

public isRoot() : bool
Return values
bool

isSubmitted()

Returns whether the form is submitted.

public isSubmitted() : bool
Return values
bool

isSynchronized()

Returns whether the data in the different formats is synchronized.

public isSynchronized() : bool
Return values
bool

isValid()

Returns whether the form and all children are valid.

public isValid() : bool
Return values
bool

offsetExists()

Returns whether a child with the given name exists (implements the \ArrayAccess interface).

public offsetExists(string $name) : bool
Parameters
$name : string

The name of the child

Return values
bool

offsetGet()

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

public offsetGet(string $name) : FormInterface
Parameters
$name : string

The name of the child

Tags
throws
OutOfBoundsException

if the named child does not exist

Return values
FormInterface

offsetSet()

Adds a child to the form (implements the \ArrayAccess interface).

public offsetSet(string $name, FormInterface $child) : void
Parameters
$name : string

Ignored. The name of the child is used

$child : FormInterface

The child to be added

Tags
throws
AlreadySubmittedException

if the form has already been submitted

throws
LogicException

when trying to add a child to a non-compound form

see
self::add()

offsetUnset()

Removes the child with the given name from the form (implements the \ArrayAccess interface).

public offsetUnset(string $name) : void
Parameters
$name : string

The name of the child to remove

Tags
throws
AlreadySubmittedException

if the form has already been submitted

remove()

Removes a child from the form.

public remove(string $name) : $this
Parameters
$name : string
Return values
$this

setData()

Updates the form with default model data.

public setData(mixed $modelData) : $this
Parameters
$modelData : mixed

The data formatted as expected for the underlying object

Return values
$this

setParent()

Sets the parent form.

public setParent([FormInterface $parent = null ]) : $this
Parameters
$parent : FormInterface = null

The parent form or null if it's the root

Return values
$this

submit()

Submits data to the form.

public submit(mixed $submittedData[, bool $clearMissing = true ]) : $this
Parameters
$submittedData : mixed

The submitted data

$clearMissing : bool = true

Whether to set fields to NULL when they are missing in the submitted data. This argument is only used in compound form

Return values
$this

modelToNorm()

Normalizes the underlying data if a model transformer is set.

private modelToNorm(mixed $value) : mixed
Parameters
$value : mixed
Tags
throws
TransformationFailedException

If the underlying data cannot be transformed to "normalized" format

normToModel()

Reverse transforms a value if a model transformer is set.

private normToModel(mixed $value) : mixed
Parameters
$value : mixed
Tags
throws
TransformationFailedException

If the value cannot be transformed to "model" format

normToView()

Transforms the value if a view transformer is set.

private normToView(mixed $value) : mixed
Parameters
$value : mixed
Tags
throws
TransformationFailedException

If the normalized value cannot be transformed to "view" format

sort()

Sorts view fields based on their priority value.

private sort(array<string|int, mixed> &$children) : void
Parameters
$children : array<string|int, mixed>

viewToNorm()

Reverse transforms a value if a view transformer is set.

private viewToNorm(mixed $value) : mixed
Parameters
$value : mixed
Tags
throws
TransformationFailedException

If the submitted value cannot be transformed to "normalized" format


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results