Symfony\Component\Form\FormBuilder

class FormBuilder extends FormConfigBuilder implements IteratorAggregate, FormBuilderInterface

A builder for creating {@link Form} instances.

Properties

protected bool

$locked

Methods

__construct(string|int $name, string|null $dataClass, EventDispatcherInterface $dispatcher, FormFactoryInterface $factory, array $options = array())

Creates an empty form configuration.

$this

addEventListener(string $eventName, callable $listener, int $priority = 0)

Adds an event listener to an event on this form.

from FormConfigBuilder

$this

addEventSubscriber(EventSubscriberInterface $subscriber)

Adds an event subscriber for events on this form.

from FormConfigBuilder

$this

addViewTransformer(DataTransformerInterface $viewTransformer, bool $forcePrepend = false)

Appends / prepends a transformer to the view transformer chain.

from FormConfigBuilder

$this

resetViewTransformers()

Clears the view transformers.

from FormConfigBuilder

$this

addModelTransformer(DataTransformerInterface $modelTransformer, bool $forceAppend = false)

Prepends / appends a transformer to the normalization transformer chain.

from FormConfigBuilder

$this

resetModelTransformers()

Clears the normalization transformers.

from FormConfigBuilder

EventDispatcherInterface

getEventDispatcher()

Returns the event dispatcher used to dispatch form events.

from FormConfigBuilder

string

getName()

Returns the name of the form used as HTTP parameter.

from FormConfigBuilder

PropertyPathInterface|null

getPropertyPath()

Returns the property path that the form should be mapped to.

from FormConfigBuilder

bool

getMapped()

Returns whether the form should be mapped to an element of its parent's data.

from FormConfigBuilder

bool

getByReference()

Returns whether the form's data should be modified by reference.

from FormConfigBuilder

bool

getInheritData()

Returns whether the form should read and write the data of its parent.

from FormConfigBuilder

bool

getCompound()

Returns whether the form is compound.

from FormConfigBuilder

ResolvedFormTypeInterface

getType()

Returns the form types used to construct the form.

from FormConfigBuilder

DataTransformerInterface[]

getViewTransformers()

Returns the view transformers of the form.

from FormConfigBuilder

DataTransformerInterface[]

getModelTransformers()

Returns the model transformers of the form.

from FormConfigBuilder

DataMapperInterface|null

getDataMapper()

Returns the data mapper of the form.

from FormConfigBuilder

bool

getRequired()

Returns whether the form is required.

from FormConfigBuilder

bool

getDisabled()

Returns whether the form is disabled.

from FormConfigBuilder

bool

getErrorBubbling()

Returns whether errors attached to the form will bubble to its parent.

from FormConfigBuilder

mixed

getEmptyData()

Returns the data that should be returned when the form is empty.

from FormConfigBuilder

array

getAttributes()

Returns additional attributes of the form.

from FormConfigBuilder

bool

hasAttribute(string $name)

Returns whether the attribute with the given name exists.

from FormConfigBuilder

mixed

getAttribute(string $name, mixed $default = null)

Returns the value of the given attribute.

from FormConfigBuilder

mixed

getData()

Returns the initial data of the form.

from FormConfigBuilder

string|null

getDataClass()

Returns the class of the form data or null if the data is scalar or an array.

from FormConfigBuilder

bool

getDataLocked()

Returns whether the form's data is locked.

from FormConfigBuilder

FormFactoryInterface

getFormFactory()

Returns the form factory used for creating new forms.

from FormConfigBuilder

string

getAction()

Returns the target URL of the form.

from FormConfigBuilder

string

getMethod()

Returns the HTTP method used by the form.

from FormConfigBuilder

RequestHandlerInterface

getRequestHandler()

Returns the request handler used by the form.

from FormConfigBuilder

bool

getAutoInitialize()

Returns whether the form should be initialized upon creation.

from FormConfigBuilder

array

getOptions()

Returns all options passed during the construction of the form.

from FormConfigBuilder

bool

hasOption(string $name)

Returns whether a specific option exists.

from FormConfigBuilder

mixed

getOption(string $name, mixed $default = null)

Returns the value of a specific option.

from FormConfigBuilder

$this

setAttribute(string $name, mixed $value)

Sets the value for an attribute.

from FormConfigBuilder

$this

setAttributes(array $attributes)

Sets the attributes.

from FormConfigBuilder

$this

setDataMapper(DataMapperInterface $dataMapper = null)

Sets the data mapper used by the form.

from FormConfigBuilder

$this

setDisabled(bool $disabled)

Set whether the form is disabled.

from FormConfigBuilder

$this

setEmptyData(mixed $emptyData)

Sets the data used for the client data when no value is submitted.

from FormConfigBuilder

$this

setErrorBubbling(bool $errorBubbling)

Sets whether errors bubble up to the parent.

from FormConfigBuilder

$this

setRequired(bool $required)

Sets whether this field is required to be filled out when submitted.

from FormConfigBuilder

$this

setPropertyPath(string|PropertyPathInterface|null $propertyPath)

Sets the property path that the form should be mapped to.

from FormConfigBuilder

$this

setMapped(bool $mapped)

Sets whether the form should be mapped to an element of its parent's data.

from FormConfigBuilder

$this

setByReference(bool $byReference)

Sets whether the form's data should be modified by reference.

from FormConfigBuilder

$this

setInheritData(bool $inheritData)

Sets whether the form should read and write the data of its parent.

from FormConfigBuilder

$this

setCompound(bool $compound)

Sets whether the form should be compound.

from FormConfigBuilder

$this

setType(ResolvedFormTypeInterface $type)

Set the types.

from FormConfigBuilder

$this

setData(mixed $data)

Sets the initial data of the form.

from FormConfigBuilder

$this

setDataLocked(bool $locked)

Locks the form's data to the data passed in the configuration.

from FormConfigBuilder

setFormFactory(FormFactoryInterface $formFactory)

Sets the form factory used for creating new forms.

from FormConfigBuilder

$this

setAction(string $action)

Sets the target URL of the form.

from FormConfigBuilder

$this

setMethod(string $method)

Sets the HTTP method used by the form.

from FormConfigBuilder

$this

setRequestHandler(RequestHandlerInterface $requestHandler)

Sets the request handler used by the form.

from FormConfigBuilder

$this

setAutoInitialize(bool $initialize)

Sets whether the form should be initialized automatically.

from FormConfigBuilder

FormConfigInterface

getFormConfig()

Builds and returns the form configuration.

static

validateName(string|int $name)

Validates whether the given variable is a valid form name.

from FormConfigBuilder

static bool

isValidName(string $name)

Returns whether the given variable contains a valid form name.

from FormConfigBuilder

FormBuilderInterface

add(string|int|FormBuilderInterface $child, string|null $type = null, array $options = array())

Adds a new field to this group. A field must have a unique name within the group. Otherwise the existing field is overwritten.

FormBuilderInterface

create(string $name, string|null $type = null, array $options = array())

Creates a form builder.

FormBuilderInterface

get(string $name)

Returns a child by name.

FormBuilderInterface

remove(string $name)

Removes the field with the given name.

bool

has(string $name)

Returns whether a field with the given name exists.

array

all()

Returns the children.

count()

{@inheritdoc}

FormInterface

getForm()

Creates the form.

FormBuilderInterface[]

getIterator()

{@inheritdoc}

Details

`__construct(string|int $name, string|null $dataClass, EventDispatcherInterface $dispatcher, FormFactoryInterface $factory, array $options = array())`

Creates an empty form configuration.

Parameters

string\|int	$name	The form name
string\|null	$dataClass	The class of the form's data
EventDispatcherInterface	$dispatcher	The event dispatcher
FormFactoryInterface	$factory
array	$options	The form options

Exceptions

InvalidArgumentException

if the data class is not a valid class or if the name contains invalid characters

`$this addEventListener(string $eventName, callable $listener, int $priority = 0)`

Adds an event listener to an event on this form.

Parameters

string	$eventName	The name of the event to listen to
callable	$listener	The listener to execute
int	$priority	The priority of the listener. Listeners with a higher priority are called before listeners with a lower priority.

Return Value

$this

The configuration object

`$this addEventSubscriber(EventSubscriberInterface $subscriber)`

Adds an event subscriber for events on this form.

Parameters

EventSubscriberInterface

$subscriber

Return Value

$this

The configuration object

`$this addViewTransformer(DataTransformerInterface $viewTransformer, bool $forcePrepend = false)`

Appends / prepends a transformer to the view transformer chain.

The transform method of the transformer is used to convert data from the normalized to the view format. The reverseTransform method of the transformer is used to convert from the view to the normalized format.

Parameters

DataTransformerInterface	$viewTransformer
bool	$forcePrepend	If set to true, prepend instead of appending

Return Value

$this

The configuration object

`$this resetViewTransformers()`

Clears the view transformers.

Return Value

$this

The configuration object

`$this addModelTransformer(DataTransformerInterface $modelTransformer, bool $forceAppend = false)`

Prepends / appends a transformer to the normalization transformer chain.

The transform method of the transformer is used to convert data from the model to the normalized format. The reverseTransform method of the transformer is used to convert from the normalized to the model format.

Parameters

DataTransformerInterface	$modelTransformer
bool	$forceAppend	If set to true, append instead of prepending

Return Value

$this

The configuration object

`$this resetModelTransformers()`

Clears the normalization transformers.

Return Value

$this

The configuration object

`EventDispatcherInterface getEventDispatcher()`

Returns the event dispatcher used to dispatch form events.

Return Value

EventDispatcherInterface

The dispatcher

`string getName()`

Returns the name of the form used as HTTP parameter.

Return Value

string

The form name

`PropertyPathInterface|null getPropertyPath()`

Returns the property path that the form should be mapped to.

Return Value

PropertyPathInterface|null

The property path

`bool getMapped()`

Returns whether the form should be mapped to an element of its parent's data.

Return Value

bool	Whether the form is mapped

`bool getByReference()`

Returns whether the form's data should be modified by reference.

Return Value

bool	Whether to modify the form's data by reference

`bool getInheritData()`

Returns whether the form should read and write the data of its parent.

Return Value

bool	Whether the form should inherit its parent's data

`bool getCompound()`

Returns whether the form is compound.

This property is independent of whether the form actually has children. A form can be compound and have no children at all, like for example an empty collection form.

Return Value

bool	Whether the form is compound

`ResolvedFormTypeInterface getType()`

Returns the form types used to construct the form.

Return Value

ResolvedFormTypeInterface

The form's type

`DataTransformerInterface[] getViewTransformers()`

Returns the view transformers of the form.

Return Value

DataTransformerInterface[]

An array of {@link DataTransformerInterface} instances

`DataTransformerInterface[] getModelTransformers()`

Returns the model transformers of the form.

Return Value

DataTransformerInterface[]

An array of {@link DataTransformerInterface} instances

`DataMapperInterface|null getDataMapper()`

Returns the data mapper of the form.

Return Value

DataMapperInterface|null

The data mapper

`bool getRequired()`

Returns whether the form is required.

Return Value

bool	Whether the form is required

`bool getDisabled()`

Returns whether the form is disabled.

Return Value

bool	Whether the form is disabled

`bool getErrorBubbling()`

Returns whether errors attached to the form will bubble to its parent.

Return Value

bool	Whether errors will bubble up

`mixed getEmptyData()`

Returns the data that should be returned when the form is empty.

Return Value

mixed

The data returned if the form is empty

`array getAttributes()`

Returns additional attributes of the form.

Return Value

array

An array of key-value combinations

`bool hasAttribute(string $name)`

Returns whether the attribute with the given name exists.

Parameters

string

$name

The attribute name

Return Value

bool	Whether the attribute exists

`mixed getAttribute(string $name, mixed $default = null)`

Returns the value of the given attribute.

Parameters

string	$name	The attribute name
mixed	$default	The value returned if the attribute does not exist

Return Value

mixed

The attribute value

`mixed getData()`

Returns the initial data of the form.

Return Value

mixed

The initial form data

`string|null getDataClass()`

Returns the class of the form data or null if the data is scalar or an array.

Return Value

string|null

The data class or null

`bool getDataLocked()`

Returns whether the form's data is locked.

A form with locked data is restricted to the data passed in this configuration. The data can only be modified then by submitting the form.

Return Value

bool	Whether the data is locked

`FormFactoryInterface getFormFactory()`

Returns the form factory used for creating new forms.

Return Value

FormFactoryInterface

The form factory

`string getAction()`

Returns the target URL of the form.

Return Value

string

The target URL of the form

`string getMethod()`

Returns the HTTP method used by the form.

Return Value

string

The HTTP method of the form

`RequestHandlerInterface getRequestHandler()`

Returns the request handler used by the form.

Return Value

RequestHandlerInterface

The request handler

`bool getAutoInitialize()`

Returns whether the form should be initialized upon creation.

Return Value

bool	returns true if the form should be initialized when created, false otherwise

`array getOptions()`

Returns all options passed during the construction of the form.

Return Value

array

The passed options

`bool hasOption(string $name)`

Returns whether a specific option exists.

Parameters

string

$name

The option name,

Return Value

bool	Whether the option exists

`mixed getOption(string $name, mixed $default = null)`

Returns the value of a specific option.

Parameters

string	$name	The option name
mixed	$default	The value returned if the option does not exist

Return Value

mixed

The option value

`$this setAttribute(string $name, mixed $value)`

Sets the value for an attribute.

Parameters

string	$name	The name of the attribute
mixed	$value	The value of the attribute

Return Value

$this

The configuration object

`$this setAttributes(array $attributes)`

Sets the attributes.

Parameters

array

$attributes

Return Value

$this

The configuration object

`$this setDataMapper(DataMapperInterface $dataMapper = null)`

Sets the data mapper used by the form.

Parameters

DataMapperInterface

$dataMapper

Return Value

$this

The configuration object

`$this setDisabled(bool $disabled)`

Set whether the form is disabled.

Parameters

bool

$disabled

Whether the form is disabled

Return Value

$this

The configuration object

`$this setEmptyData(mixed $emptyData)`

Sets the data used for the client data when no value is submitted.

Parameters

mixed

$emptyData

The empty data

Return Value

$this

The configuration object

`$this setErrorBubbling(bool $errorBubbling)`

Sets whether errors bubble up to the parent.

Parameters

bool

$errorBubbling

Return Value

$this

The configuration object

`$this setRequired(bool $required)`

Sets whether this field is required to be filled out when submitted.

Parameters

bool

$required

Return Value

$this

The configuration object

`$this setPropertyPath(string|PropertyPathInterface|null $propertyPath)`

Sets the property path that the form should be mapped to.

Parameters

string|PropertyPathInterface|null

$propertyPath

The property path or null if the path should be set automatically based on the form's name

Return Value

$this

The configuration object

`$this setMapped(bool $mapped)`

Sets whether the form should be mapped to an element of its parent's data.

Parameters

bool

$mapped

Whether the form should be mapped

Return Value

$this

The configuration object

`$this setByReference(bool $byReference)`

Sets whether the form's data should be modified by reference.

Parameters

bool

$byReference

Whether the data should be modified by reference

Return Value

$this

The configuration object

`$this setInheritData(bool $inheritData)`

Sets whether the form should read and write the data of its parent.

Parameters

bool

$inheritData

Whether the form should inherit its parent's data

Return Value

$this

The configuration object

`$this setCompound(bool $compound)`

Sets whether the form should be compound.

Parameters

bool

$compound

Whether the form should be compound

Return Value

$this

The configuration object

`$this setType(ResolvedFormTypeInterface $type)`

Set the types.

Parameters

ResolvedFormTypeInterface

$type

Return Value

$this

The configuration object

`$this setData(mixed $data)`

Sets the initial data of the form.

Parameters

mixed

$data

The data of the form in application format

Return Value

$this

The configuration object

`$this setDataLocked(bool $locked)`

Locks the form's data to the data passed in the configuration.

A form with locked data is restricted to the data passed in this configuration. The data can only be modified then by submitting the form.

Parameters

bool

$locked

Whether to lock the default data

Return Value

$this

The configuration object

`setFormFactory(FormFactoryInterface $formFactory)`

Sets the form factory used for creating new forms.

Parameters

FormFactoryInterface

$formFactory

`$this setAction(string $action)`

Sets the target URL of the form.

Parameters

string

$action

The target URL of the form

Return Value

$this

The configuration object

`$this setMethod(string $method)`

Sets the HTTP method used by the form.

Parameters

string

$method

The HTTP method of the form

Return Value

$this

The configuration object

`$this setRequestHandler(RequestHandlerInterface $requestHandler)`

Sets the request handler used by the form.

Parameters

RequestHandlerInterface

$requestHandler

Return Value

$this

The configuration object

`$this setAutoInitialize(bool $initialize)`

Sets whether the form should be initialized automatically.

Should be set to true only for root forms.

Parameters

bool

$initialize

True to initialize the form automatically, false to suppress automatic initialization. In the second case, you need to call {@link FormInterface::initialize()} manually.

Return Value

$this

The configuration object

`FormConfigInterface getFormConfig()`

Builds and returns the form configuration.

Return Value

FormConfigInterface

`static validateName(string|int $name)`

Validates whether the given variable is a valid form name.

Parameters

string|int

$name

The tested form name

Exceptions

UnexpectedTypeException	if the name is not a string or an integer
InvalidArgumentException	if the name contains invalid characters

`static bool isValidName(string $name)`

Returns whether the given variable contains a valid form name.

A name is accepted if it

is empty
starts with a letter, digit or underscore
contains only letters, digits, numbers, underscores ("_"), hyphens ("-") and colons (":")

Parameters

string

$name

The tested form name

Return Value

bool	Whether the name is valid

`FormBuilderInterface add(string|int|FormBuilderInterface $child, string|null $type = null, array $options = array())`

Adds a new field to this group. A field must have a unique name within the group. Otherwise the existing field is overwritten.

If you add a nested group, this group should also be represented in the object hierarchy.

Parameters

string\|int\|FormBuilderInterface	$child
string\|null	$type
array	$options

Return Value

FormBuilderInterface

`FormBuilderInterface create(string $name, string|null $type = null, array $options = array())`

Creates a form builder.

Parameters

string	$name	The name of the form or the name of the property
string\|null	$type	The type of the form or null if name is a property
array	$options	The options

Return Value

FormBuilderInterface

`FormBuilderInterface get(string $name)`

Returns a child by name.

Parameters

string

$name

The name of the child

Return Value

FormBuilderInterface

Exceptions

InvalidArgumentException

if the given child does not exist

`FormBuilderInterface remove(string $name)`

Removes the field with the given name.

Parameters

string

$name

Return Value

FormBuilderInterface

`bool has(string $name)`

Returns whether a field with the given name exists.

Parameters

string

$name

Return Value

bool

`array all()`

Returns the children.

Return Value

array

`count()`

{@inheritdoc}

`FormInterface getForm()`

Creates the form.

Return Value

FormInterface

The form

`FormBuilderInterface[] getIterator()`

{@inheritdoc}

Return Value

FormBuilderInterface[]