Documentation

FormInterface extends ArrayAccess, Traversable, Countable
in

A form group bundling multiple forms in a hierarchical structure.

Tags
author

Bernhard Schussek bschussek@gmail.com

extends

\ArrayAccess<string, FormInterface>

extends

\Traversable<string, FormInterface>

Table of Contents

Methods

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.
createView()  : FormView
get()  : self
Returns the child with the given name.
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.
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()  : self|null
Returns the parent form.
getPropertyPath()  : PropertyPathInterface|null
Returns the property path that the form is mapped to.
getRoot()  : self
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.
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.

Methods

add()

Adds or replaces a child to the form.

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

The FormInterface instance or the name of the child

$type : string|null = null

The child's type, if a name was passed

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

The child's options, if a name was passed

Tags
throws
AlreadySubmittedException

if the form has already been submitted

throws
LogicException

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

throws
UnexpectedTypeException

if $child or $type has an unexpected type

Return values
$this

all()

Returns all children in this group.

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

get()

Returns the child with the given name.

public get(string $name) : self
Parameters
$name : string
Tags
throws
OutOfBoundsException

if the named child does not exist

Return values
self

getData()

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

public getData() : mixed
Tags
throws
RuntimeException

If the form inherits data but has no parent

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

getName()

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

public getName() : string

Only root forms are allowed to have an empty name.

Return values
string

getNormData()

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

public getNormData() : mixed
Tags
throws
RuntimeException

If the form inherits data but has no parent

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.

getParent()

Returns the parent form.

public getParent() : self|null
Return values
self|null

getRoot()

Returns the root of the form tree.

public getRoot() : self
Return values
self

getViewData()

Returns the view data of the field.

public getViewData() : mixed

It may be defined by .

There are two cases:

  • When the form is compound the view data is mapped to the children. Each child will use its mapped data as model data. It can be an array, an object or null.

  • When the form is simple its view data is used to be bound to the submitted data. It can be a string or an array.

In both cases the view data is the actual altered data on submission.

Tags
throws
RuntimeException

If the form inherits data but has no parent

handleRequest()

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

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

Internally, the request is forwarded to the configured instance, which determines whether to submit the form or not.

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

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

Tags
throws
RuntimeException

If the form is not the root

Return values
$this

isDisabled()

Returns whether this form is disabled.

public isDisabled() : bool

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 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

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 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

If the data is not synchronized, you can get the transformation failure by calling .

If the form is not submitted, this method always returns true.

Return values
bool

isValid()

Returns whether the form and all children are valid.

public isValid() : bool
Tags
throws
LogicException

if the form is not submitted

Return values
bool

remove()

Removes a child from the form.

public remove(string $name) : $this
Parameters
$name : string
Tags
throws
AlreadySubmittedException

if the form has already been submitted

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

Tags
throws
AlreadySubmittedException

If the form has already been submitted

throws
LogicException

if the view data does not match the expected type according to

throws
RuntimeException

If listeners try to call setData in a cycle or if the form inherits data from its parent

throws
TransformationFailedException

if the synchronization failed

Return values
$this

submit()

Submits data to the form.

public submit(string|array<string|int, mixed>|null $submittedData[, bool $clearMissing = true ]) : $this
Parameters
$submittedData : string|array<string|int, mixed>|null

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

Tags
throws
AlreadySubmittedException

if the form has already been submitted

Return values
$this 

        

        
    




    

    

                                

                

                            
    

        On this page

        
    


                

                            

            

    

        

            
Search results