‪TYPO3CMS  11.5
TYPO3\CMS\Form\Domain\Model\FormDefinition Class Reference
Inheritance diagram for TYPO3\CMS\Form\Domain\Model\FormDefinition:
TYPO3\CMS\Form\Domain\Model\Renderable\AbstractCompositeRenderable TYPO3\CMS\Form\Domain\Model\Renderable\VariableRenderableInterface TYPO3\CMS\Form\Domain\Model\Renderable\AbstractRenderable TYPO3\CMS\Form\Domain\Model\Renderable\CompositeRenderableInterface TYPO3\CMS\Form\Domain\Model\Renderable\RenderableInterface TYPO3\CMS\Form\Domain\Model\Renderable\VariableRenderableInterface TYPO3\CMS\Form\Domain\Model\Renderable\RenderableInterface TYPO3\CMS\Form\Domain\Model\Renderable\RootRenderableInterface TYPO3\CMS\Form\Domain\Model\Renderable\RootRenderableInterface

Public Member Functions

 setOptions (array $options, bool $resetFinishers=false)
Page createPage (string $identifier, string $typeName='Page')
 addPage (Page $page)
bool hasPageWithIndex (int $index)
Page getPageByIndex (int $index)
 addFinisher (FinisherInterface $finisher)
FinisherInterface createFinisher (string $finisherIdentifier, array $options=[])
list< FinisherInterfacegetFinishers ()
 registerRenderable (RenderableInterface $renderable)
 unregisterRenderable (RenderableInterface $renderable)
FormElementInterface null getElementByIdentifier (string $elementIdentifier)
 addElementDefaultValue (string $elementIdentifier, $defaultValue)
mixed getElementDefaultValueByIdentifier (string $elementIdentifier)
 movePageBefore (Page $pageToMove, Page $referencePage)
 movePageAfter (Page $pageToMove, Page $referencePage)
 removePage (Page $pageToRemove)
FormRuntime bind (Request $request)
ProcessingRule getProcessingRule (string $propertyPath)
string getPersistenceIdentifier ()
 setRendererClassName (string $rendererClassName)
string getRendererClassName ()
- ‪Public Member Functions inherited from ‪TYPO3\CMS\Form\Domain\Model\Renderable\AbstractCompositeRenderable
RenderableInterface[] getRenderablesRecursively ()
 registerInFormIfPossible ()
 onRemoveFromParentRenderable ()
- ‪Public Member Functions inherited from ‪TYPO3\CMS\Form\Domain\Model\Renderable\AbstractRenderable
string getType ()
string getIdentifier ()
 setIdentifier (string $identifier)
mixed createValidator (string $validatorIdentifier, array $options=[])
 addValidator (ValidatorInterface $validator)
SplObjectStorage getValidators ()
 setDataType (string $dataType)
array getRenderingOptions ()
mixed setRenderingOption (string $key, $value)
CompositeRenderableInterface null getParentRenderable ()
 setParentRenderable (CompositeRenderableInterface $parentRenderable)
FormDefinition getRootForm ()
int getIndex ()
 setIndex (int $index)
string getLabel ()
 setLabel (string $label)
 setDefaultValue ($defaultValue)
 setProperty (string $key, $value)
string getTemplateName ()
bool isEnabled ()
RenderableVariantInterface[] getVariants ()
RenderableVariantInterface createVariant (array $options)
 addVariant (RenderableVariantInterface $variant)
 applyVariant (RenderableVariantInterface $variant)

Public Attributes

array< int, function getPages():array { return $this-> renderables
array< string, function getElements():array { return $this-> elementsByIdentifier
array< string, function getProcessingRules():array { return $this-> processingRules
array< string, function getTypeDefinitions():array { return $this-> typeDefinitions
array< string, function getValidatorsDefinition():array { return $this-> validatorsDefinition

Protected Member Functions

array< int, $renderables=array();protected list< FinisherInterface > $finishers=array();protected array< string, $processingRules=array();protected array< string, $elementsByIdentifier=array();protected array< string, $elementDefaultValues=array();protected string $rendererClassName='';protected array< string, $typeDefinitions;protected array< string, $validatorsDefinition;protected array< string, $finishersDefinition;protected string $persistenceIdentifier;public __construct(string $identifier, array $prototypeConfiguration=[], string $type='Form', ?string $persistenceIdentifier=null) { $this->typeDefinitions=$prototypeConfiguration[ 'formElementsDefinition'] ??[];$this->validatorsDefinition=$prototypeConfiguration[ 'validatorsDefinition'] ??[];$this->finishersDefinition=$prototypeConfiguration[ 'finishersDefinition'] ??[];if(!is_string( $identifier)||strlen( $identifier)===0) { throw new IdentifierNotValidException( 'The given identifier was not a string or the string was empty.', 1477082503);} $this->identifier=$identifier;$this->type=$type;$this->persistenceIdentifier=(string) $persistenceIdentifier;if( $prototypeConfiguration !==[]) { $this-> initializeFromFormDefaults ()
 initializeFromFormDefaults ()
- ‪Protected Member Functions inherited from ‪TYPO3\CMS\Form\Domain\Model\Renderable\AbstractCompositeRenderable
 addRenderable (RenderableInterface $renderable)
 moveRenderableBefore (RenderableInterface $renderableToMove, RenderableInterface $referenceRenderable)
 moveRenderableAfter (RenderableInterface $renderableToMove, RenderableInterface $referenceRenderable)
 removeRenderable (RenderableInterface $renderableToRemove)

Additional Inherited Members

- ‪Protected Attributes inherited from ‪TYPO3\CMS\Form\Domain\Model\Renderable\AbstractCompositeRenderable
TYPO3 CMS Form Domain Model Renderable RenderableInterface[] $renderables = array( )
- ‪Protected Attributes inherited from ‪TYPO3\CMS\Form\Domain\Model\Renderable\AbstractRenderable
string $type
string $identifier
CompositeRenderableInterface null $parentRenderable
string $label = ''
array $renderingOptions = array( )
int $index = 0
string $templateName = ''
array $variants = array( )

Detailed Description

This class encapsulates a complete Form Definition, with all of its pages, form elements, validation rules which apply and finishers which should be executed when the form is completely filled in.

It is not modified when the form executes.

The Anatomy Of A Form

A FormDefinition consists of multiple Page (Page) objects. When a form is displayed to the user, only one Page is visible at any given time, and there is a navigation to go back and forth between the pages.

A Page consists of multiple FormElements (FormElementInterface, AbstractFormElement), which represent the input fields, textareas, checkboxes shown inside the page.

FormDefinition, Page and FormElement have identifier properties, which must be unique for each given type (i.e. it is allowed that the FormDefinition and a FormElement have the same identifier, but two FormElements are not allowed to have the same identifier.

Simple Example

Generally, you can create a FormDefinition manually by just calling the API methods on it, or you use a Form Definition Factory to build the form from another representation format such as YAML.

/—code php $formDefinition = GeneralUtility::makeInstance(FormDefinition::class, 'myForm');

$page1 = GeneralUtility::makeInstance(Page::class, 'page1'); $formDefinition->addPage($page);

$element1 = GeneralUtility::makeInstance(GenericFormElement::class, 'title', 'Textfield'); # the second argument is the type of the form element $page1->addElement($element1); ---

Creating a Form, Using Abstract Form Element Types

While you can use the FormDefinition::addPage or Page::addElement methods and create the Page and FormElement objects manually, it is often better to use the corresponding create* methods (FormDefinition::createPage and Page::createElement), as you pass them an abstract Form Element Type such as Text or Page, and the system automatically resolves the implementation class name and sets default values.

So the simple example from above should be rewritten as follows:

/—code php $prototypeConfiguration = []; // We'll talk about this later

$formDefinition = GeneralUtility::makeInstance(FormDefinition::class, 'myForm', $prototypeConfiguration); $page1 = $formDefinition->createPage('page1'); $element1 = $page1->addElement('title', 'Textfield'); ---

Now, you might wonder how the system knows that the element Textfield is implemented using a GenericFormElement: This is configured in the $prototypeConfiguration.

To make the example from above actually work, we need to add some sensible values to $prototypeConfiguration:

$prototypeConfiguration = [
  'formElementsDefinition' => [
    'Page' => [
      'implementationClassName' => 'TYPO3\CMS\Form\Domain\Model\FormElements\Page'
    'Textfield' => [
      'implementationClassName' => 'TYPO3\CMS\Form\Domain\Model\FormElements\GenericFormElement'

For each abstract Form Element Type we add some configuration; in the above case only the implementation class name. Still, it is possible to set defaults for all configuration options of such an element, as the following example shows:

$prototypeConfiguration = [
  'formElementsDefinition' => [
    'Page' => [
      'implementationClassName' => 'TYPO3\CMS\Form\Domain\Model\FormElements\Page',
      'label' => 'this is the label of the page if nothing is specified'
    'Textfield' => [
      'implementationClassName' => 'TYPO3\CMS\Form\Domain\Model\FormElements\GenericFormElement',
      'label' = >'Default Label',
      'defaultValue' => 'Default form element value',
      'properties' => [
        'placeholder' => 'Text which is shown if element is empty'


sing Preconfigured $prototypeConfiguration

Often, it is not really useful to manually create the $prototypeConfiguration array.

Most of it comes pre-configured inside the YAML settings of the extensions, and the \TYPO3\CMS\Form\Domain\Configuration\ConfigurationService contains helper methods which return the ready-to-use $prototypeConfiguration.

Property Mapping and Validation Rules

Besides Pages and FormElements, the FormDefinition can contain information about the format of the data which is inputted into the form. This generally means:

  • ‪expected Data Types
  • ‪Property Mapping Configuration to be used
  • ‪Validation Rules which should apply

Background Info

You might wonder why Data Types and Validation Rules are not attached to each FormElement itself.

If the form should create a hierarchical output structure such as a multi- dimensional array or a PHP object, your expected data structure might look as follows:

  • ‪person -- firstName -- lastName -- address --- street --- city
Now, let's imagine you want to edit person.address.street and person.address.city,
but want to validate that the combination of street and city is valid
according to some address database.
In this case, the form elements would be configured to fill street and city,
but the validator needs to be attached to the compound object address,
as both parts need to be validated together.

Connecting FormElements to the output data structure

The identifier of the FormElement is most important, as it determines
where in the output structure the value which is entered by the user is placed,
and thus also determines which validation rules need to apply.
Using the above example, if you want to create a FormElement for the street,
you should use the identifier person.address.street.

Rendering a FormDefinition

In order to trigger rendering on a FormDefinition,
the current \TYPO3\CMS\Extbase\Mvc\Request needs to be bound to the FormDefinition,
resulting in a \TYPO3\CMS\Form\Domain\Runtime\FormRuntime object which contains the Runtime State of the form
(such as the currently inserted values).
/—code php

$currentRequest and $currentResponse need to be available, f.e. inside a controller you would

use $this->request. Inside a ViewHelper you would use $this->renderingContext->getRequest()

$form = $formDefinition->bind($currentRequest);

now, you can use the $form object to get information about the currently

entered values into the form, etc.

Refer to the \TYPO3\CMS\Form\Domain\Runtime\FormRuntime API doc for further information.
Scope: frontend
This class is NOT meant to be sub classed by developers.
 May change any time, use FormFactoryInterface to select a different FormDefinition if needed
‪: Declare final in v12

Definition at line 225 of file FormDefinition.php.

Member Function Documentation

◆ addElementDefaultValue()

TYPO3\CMS\Form\Domain\Model\FormDefinition::addElementDefaultValue ( string  $elementIdentifier,

Sets the default value of a form element

string$elementIdentifier‪identifier of the form element. This supports property paths!

Definition at line 616 of file FormDefinition.php.

References TYPO3\CMS\Core\Utility\ArrayUtility\setValueByPath().

◆ addFinisher()

TYPO3\CMS\Form\Domain\Model\FormDefinition::addFinisher ( FinisherInterface  $finisher)

Adds the specified finisher to this form


Definition at line 494 of file FormDefinition.php.

Referenced by TYPO3\CMS\Form\Domain\Model\FormDefinition\createFinisher().

◆ addPage()

TYPO3\CMS\Form\Domain\Model\FormDefinition::addPage ( Page  $page)

Add a new page at the end of the form.

Instead of this method, you should often use createPage instead.

FormDefinitionConsistencyException‪if Page is already added to a FormDefinition
See also

Definition at line 446 of file FormDefinition.php.

References TYPO3\CMS\Form\Domain\Model\Renderable\AbstractCompositeRenderable\addRenderable().

Referenced by TYPO3\CMS\Form\Domain\Model\FormDefinition\createPage().

◆ bind()

FormRuntime TYPO3\CMS\Form\Domain\Model\FormDefinition::bind ( Request  $request)

Bind the current request & response to this form instance, effectively creating a new "instance" of the Form.


Definition at line 678 of file FormDefinition.php.

◆ createFinisher()

FinisherInterface TYPO3\CMS\Form\Domain\Model\FormDefinition::createFinisher ( string  $finisherIdentifier,
array  $options = [] 
string$finisherIdentifier‪identifier of the finisher as registered in the current form (for example: "Redirect")
array$options‪options for this finisher in the format ['option1' => 'value1', 'option2' => 'value2', ...]

Definition at line 505 of file FormDefinition.php.

References TYPO3\CMS\Form\Domain\Model\FormDefinition\addFinisher(), and TYPO3\CMS\Core\Utility\ArrayUtility\mergeRecursiveWithOverrule().

Referenced by TYPO3\CMS\Form\Domain\Model\FormDefinition\setOptions().

◆ createPage()

Page TYPO3\CMS\Form\Domain\Model\FormDefinition::createPage ( string  $identifier,
string  $typeName = 'Page' 

Create a page with the given $identifier and attach this page to the form.

  • ‪Create Page object based on the given $typeName
  • ‪set defaults inside the Page object
  • ‪attach Page object to this form
  • ‪return the newly created Page object
string$identifier‪Identifier of the new page
string$typeNameType of the new page
‪Page the newly created page

Definition at line 385 of file FormDefinition.php.

References TYPO3\CMS\Form\Domain\Model\Renderable\AbstractRenderable\$identifier, TYPO3\CMS\Form\Domain\Model\FormDefinition\addPage(), TYPO3\CMS\Core\Utility\ArrayUtility\assertAllArrayKeysAreValid(), and TYPO3\CMS\Form\Domain\Model\FormDefinition\typeDefinitions.

◆ getElementByIdentifier()

FormElementInterface null TYPO3\CMS\Form\Domain\Model\FormDefinition::getElementByIdentifier ( string  $elementIdentifier)

Get a Form Element by its identifier

If identifier does not exist, returns NULL.

‪FormElementInterface|null The element with the given $elementIdentifier or NULL if none found

Definition at line 604 of file FormDefinition.php.

References TYPO3\CMS\Form\Domain\Model\FormDefinition\elementsByIdentifier.

Referenced by TYPO3\CMS\Form\Domain\Finishers\AbstractFinisher\resolveRuntimeReference().

◆ getElementDefaultValueByIdentifier()

mixed TYPO3\CMS\Form\Domain\Model\FormDefinition::getElementDefaultValueByIdentifier ( string  $elementIdentifier)

returns the default value of the specified form element or NULL if no default value was set

string$elementIdentifier‪identifier of the form element. This supports property paths!
‪mixed The elements default value

Definition at line 634 of file FormDefinition.php.

References TYPO3\CMS\Extbase\Reflection\ObjectAccess\getPropertyPath().

◆ getFinishers()

list<FinisherInterface> TYPO3\CMS\Form\Domain\Model\FormDefinition::getFinishers ( )

Gets all finishers of this form


Definition at line 551 of file FormDefinition.php.

◆ getPageByIndex()

Page TYPO3\CMS\Form\Domain\Model\FormDefinition::getPageByIndex ( int  $index)

Get the page with the passed index. The first page has index zero.

If page at $index does not exist, an exception is thrown.

See also
‪Page the page
FormException‪if the specified index does not exist

Definition at line 481 of file FormDefinition.php.

References TYPO3\CMS\Form\Domain\Model\Renderable\AbstractRenderable\$index, TYPO3\CMS\Form\Domain\Model\FormDefinition\hasPageWithIndex(), and TYPO3\CMS\Form\Domain\Model\FormDefinition\renderables.

Referenced by TYPO3\CMS\Form\Domain\Runtime\FormRuntime\getConditionResolver().

◆ getPersistenceIdentifier()

string TYPO3\CMS\Form\Domain\Model\FormDefinition::getPersistenceIdentifier ( )

Get the persistence identifier of the form


Definition at line 734 of file FormDefinition.php.

◆ getProcessingRule()

ProcessingRule TYPO3\CMS\Form\Domain\Model\FormDefinition::getProcessingRule ( string  $propertyPath)

Definition at line 691 of file FormDefinition.php.

References TYPO3\CMS\Form\Domain\Model\FormDefinition\processingRules.

Referenced by TYPO3\CMS\Form\Domain\Model\Renderable\AbstractRenderable\setOptions().

◆ getRendererClassName()

string TYPO3\CMS\Form\Domain\Model\FormDefinition::getRendererClassName ( )

Get the classname of the renderer


Reimplemented from TYPO3\CMS\Form\Domain\Model\Renderable\AbstractRenderable.

Definition at line 754 of file FormDefinition.php.

Referenced by TYPO3\CMS\Form\Domain\Model\Renderable\AbstractRenderable\getRendererClassName().

◆ hasPageWithIndex()

bool TYPO3\CMS\Form\Domain\Model\FormDefinition::hasPageWithIndex ( int  $index)

Check whether a page with the given $index exists

‪bool TRUE if a page with the given $index exists, otherwise FALSE

Definition at line 467 of file FormDefinition.php.

References TYPO3\CMS\Form\Domain\Model\FormDefinition\renderables.

Referenced by TYPO3\CMS\Form\Domain\Model\FormDefinition\getPageByIndex().

◆ initializeFromFormDefaults() [1/2]

array<int, $renderables = array( ); protected list<FinisherInterface> $finishers = array( ); protected array<string, $processingRules = array( ); protected array<string, $elementsByIdentifier = array( ); protected array<string, $elementDefaultValues = array( ); protected string $rendererClassName = ''; protected array<string, $typeDefinitions; protected array<string, $validatorsDefinition; protected array<string, $finishersDefinition; protected string $persistenceIdentifier; public __construct( string $identifier, array $prototypeConfiguration = [], string $type = 'Form', ?string $persistenceIdentifier = null ) { $this->typeDefinitions = $prototypeConfiguration['formElementsDefinition'] ?? []; $this->validatorsDefinition = $prototypeConfiguration['validatorsDefinition'] ?? []; $this->finishersDefinition = $prototypeConfiguration['finishersDefinition'] ?? []; if (!is_string($identifier) || strlen($identifier) === 0) { throw new IdentifierNotValidException('The given identifier was not a string or the string was empty.', 1477082503); } $this->identifier = $identifier; $this->type = $type; $this->persistenceIdentifier = (string)$persistenceIdentifier; if ($prototypeConfiguration !== []) { $this-> TYPO3\CMS\Form\Domain\Model\FormDefinition::initializeFromFormDefaults ( )

The Form's pages


◆ initializeFromFormDefaults() [2/2]

TYPO3\CMS\Form\Domain\Model\FormDefinition::initializeFromFormDefaults ( )

Initialize the form defaults of the current type


Definition at line 320 of file FormDefinition.php.

References TYPO3\CMS\Form\Domain\Model\Renderable\AbstractRenderable\$type, TYPO3\CMS\Form\Domain\Model\FormDefinition\setOptions(), and TYPO3\CMS\Form\Domain\Model\FormDefinition\typeDefinitions.

◆ movePageAfter()

TYPO3\CMS\Form\Domain\Model\FormDefinition::movePageAfter ( Page  $pageToMove,
Page  $referencePage 

Move $pageToMove after $referencePage


Definition at line 656 of file FormDefinition.php.

References TYPO3\CMS\Form\Domain\Model\Renderable\AbstractCompositeRenderable\moveRenderableAfter().

◆ movePageBefore()

TYPO3\CMS\Form\Domain\Model\FormDefinition::movePageBefore ( Page  $pageToMove,
Page  $referencePage 

Move $pageToMove before $referencePage


Definition at line 645 of file FormDefinition.php.

References TYPO3\CMS\Form\Domain\Model\Renderable\AbstractCompositeRenderable\moveRenderableBefore().

◆ registerRenderable()

TYPO3\CMS\Form\Domain\Model\FormDefinition::registerRenderable ( RenderableInterface  $renderable)

Add an element to the ElementsByIdentifier Cache.


Definition at line 563 of file FormDefinition.php.

References TYPO3\CMS\Form\Domain\Model\FormDefinition\elementsByIdentifier, and TYPO3\CMS\Form\Domain\Model\Renderable\RootRenderableInterface\getIdentifier().

◆ removePage()

TYPO3\CMS\Form\Domain\Model\FormDefinition::removePage ( Page  $pageToRemove)

Remove $pageToRemove from form


Definition at line 666 of file FormDefinition.php.

References TYPO3\CMS\Form\Domain\Model\Renderable\AbstractCompositeRenderable\removeRenderable().

◆ setOptions()

TYPO3\CMS\Form\Domain\Model\FormDefinition::setOptions ( array  $options,
bool  $resetFinishers = false 

◆ setRendererClassName()

TYPO3\CMS\Form\Domain\Model\FormDefinition::setRendererClassName ( string  $rendererClassName)

Set the renderer class name


Definition at line 744 of file FormDefinition.php.

Referenced by TYPO3\CMS\Form\Domain\Model\FormDefinition\setOptions().

◆ unregisterRenderable()

TYPO3\CMS\Form\Domain\Model\FormDefinition::unregisterRenderable ( RenderableInterface  $renderable)

Remove an element from the ElementsByIdentifier cache


Definition at line 579 of file FormDefinition.php.

References TYPO3\CMS\Form\Domain\Model\FormDefinition\elementsByIdentifier, and TYPO3\CMS\Form\Domain\Model\Renderable\RootRenderableInterface\getIdentifier().

Member Data Documentation

◆ elementsByIdentifier

array<string, function getElements(): array { return $this-> TYPO3\CMS\Form\Domain\Model\FormDefinition::elementsByIdentifier

Get all form elements with their identifiers as keys

‪array<string, FormElementInterface>

Definition at line 593 of file FormDefinition.php.

Referenced by TYPO3\CMS\Form\Domain\Model\FormDefinition\getElementByIdentifier(), TYPO3\CMS\Form\Domain\Model\FormDefinition\registerRenderable(), and TYPO3\CMS\Form\Domain\Model\FormDefinition\unregisterRenderable().

◆ processingRules

array<string, function getProcessingRules(): array { return $this-> TYPO3\CMS\Form\Domain\Model\FormDefinition::processingRules

Get all mapping rules

‪array<string, ProcessingRule>

Definition at line 707 of file FormDefinition.php.

Referenced by TYPO3\CMS\Form\Domain\Model\FormDefinition\getProcessingRule().

◆ renderables

array<int, function getPages(): array { return $this-> TYPO3\CMS\Form\Domain\Model\FormDefinition::renderables

Get the Form's pages

‪array<int, Page> The Form's pages in the correct order

Definition at line 458 of file FormDefinition.php.

Referenced by TYPO3\CMS\Form\Domain\Model\FormDefinition\getPageByIndex(), and TYPO3\CMS\Form\Domain\Model\FormDefinition\hasPageWithIndex().

◆ typeDefinitions

array<string, function getTypeDefinitions(): array { return $this-> TYPO3\CMS\Form\Domain\Model\FormDefinition::typeDefinitions
‪array<string, array<string, mixed>>

Definition at line 716 of file FormDefinition.php.

Referenced by TYPO3\CMS\Form\Domain\Model\FormDefinition\createPage(), and TYPO3\CMS\Form\Domain\Model\FormDefinition\initializeFromFormDefaults().

◆ validatorsDefinition

array<string, function getValidatorsDefinition(): array { return $this-> TYPO3\CMS\Form\Domain\Model\FormDefinition::validatorsDefinition
‪array<string, array<string, mixed>>

Definition at line 725 of file FormDefinition.php.