FlexFormTools

readonly class \TYPO3\CMS\Core\Configuration\FlexForm\FlexFormTools

Unified service class for TCA type="flex" operations.

This service provides comprehensive FlexForm handling capabilities that work with both:

  • TCA Schema objects (high-level, schema-aware operations)
  • Raw TCA configuration arrays (low-level operations during schema building)

Note: Using the raw TCA configuration is not recommended and only available to support FlexFormTools during schema building. For extensions this might be the case on using BeforeTcaOverridesEvent or AfterTcaCompilationEvent.

Usage examples:

// With TCA Schema (typical application usage)
$flexFormTools->getDataStructureIdentifier($fieldTca, $table, $field, $row, $tcaSchema);

// With raw TCA array (only during schema)
$flexFormTools->getDataStructureIdentifier($fieldTca, $table, $field, $row, $rawTcaArray);

The service automatically detects the input type and uses the appropriate resolution strategy.

Attributes

#[Autoconfigure]
$public: true

Table of Contents

Methods

__construct()  : mixed
cleanFlexFormXML()  : string
Clean up FlexForm value XML to hold only the values it may according to its Data Structure.
convertFlexFormContentToArray()  : array
Parses the flexForm XML string and converts it to an array.
convertFlexFormContentToSheetsArray()  : array
Parses the flexForm XML string and converts it to an array.
flexArray2Xml()  : string
Convert FlexForm data array to XML
getDataStructureIdentifier()  : string
The method locates a specific data structure from given TCA and row combination and returns an identifier string that can be handed around, and can be resolved to a single data structure later without giving $row and $tca data again.
parseDataStructureByIdentifier()  : array
Parse a data structure identified by $identifier to the final data structure array.
convertDataStructureToArray()  : array
ensureDefaultSheet()  : array
Ensures a data structure has a default sheet, and no duplicate data
getDefaultDataStructureIdentifier()  : array
Finds data structure in TCA, defined in column config 'ds'
getDefaultStructureForIdentifier()  : string
Finds and returns the data structure from TCA - defined in column config 'ds'
getRecordTypeSpecificFieldConfig()  : array
Returns the record type specific configuration, also already taking columnsOverrides into account.
resolveFileDirectives()  : array
Resolve FILE:EXT and EXT: for single sheets

Methods

cleanFlexFormXML()

Clean up FlexForm value XML to hold only the values it may according to its Data Structure.

public cleanFlexFormXML(string $table, string $field, array $row, array|TcaSchema $schema) : string

The order of tags will follow that of the data structure.

Parameters

$table : string
$field : string
$row : array
$schema : array|TcaSchema

Main schema only, no sub schema! Using the raw TCA configuration is furthermore not recommended and only available to support FlexFormTools during schema building. For extensions this might be the case on using BeforeTcaOverridesEvent or AfterTcaCompilationEvent.

Return values

string

convertFlexFormContentToArray()

Parses the flexForm XML string and converts it to an array.

public convertFlexFormContentToArray(string $flexFormContent) : array

The resulting array will be multidimensional, as a value "bla.blubb" results in two levels, and a value "bla.blubb.bla" results in three levels.

Parameters

$flexFormContent : string

Return values

array

convertFlexFormContentToSheetsArray()

Parses the flexForm XML string and converts it to an array.

public convertFlexFormContentToSheetsArray(string $flexFormContent) : array

The resulting array will be multidimensional. Sheets are respected to support property paths in multiple sheets.

A value such as "settings.pageId" results in three levels: "'sDEF' => ['settings' => ['pageId' => 123]]" and a value such as "settings.storages.newsPid" results in four levels: "'sDEF' => ['settings' => ['storages' => ['newsPid' => 123]]]"

Parameters

$flexFormContent : string

flexForm xml string

Return values

array

flexArray2Xml()

Convert FlexForm data array to XML

public flexArray2Xml(array $array) : string

Parameters

$array : array

Return values

string

getDataStructureIdentifier()

The method locates a specific data structure from given TCA and row combination and returns an identifier string that can be handed around, and can be resolved to a single data structure later without giving $row and $tca data again.

public getDataStructureIdentifier(array $fieldTca, string $tableName, string $fieldName, array $row[, array|TcaSchema|null $schema = null ]) : string

Note: The returned syntax is meant to only specify the target location of the data structure. It SHOULD NOT be abused and enriched with data from the record that is dealt with. For instance, it is not allowed to add source record specific date like the "uid" or the "pid"! If that is done, it is up to the hook consumer to take care of possible side effects, e.g. if the DataHandler copies or moves records around and those references change.

This method gets: Source data that influences the target location of a data structure This method returns: Target specification of the data structure

This method is "paired" with method parseDataStructureByIdentifier() that will resolve the returned syntax again and returns the data structure itself.

Both methods can be extended via events to return and accept additional identifier strings if needed, and to transmit further information within the identifier strings.

Important: The TCA for data structure definitions MUST be overridden by 'columnsOverrides' as the "ds" config is a string, containing the data structure or a file pointer.

Note: This method and the resolving methods below are well unit tested and document all nasty details this way.

Parameters

$fieldTca : array

Full TCA of the field in question that has type=flex set

$tableName : string

The table name of the TCA field

$fieldName : string

The field name

$row : array

The data row

$schema : array|TcaSchema|null = null

Either be the Tca Schema object or raw TCA configuration. Only omit in case handling is done via events. Otherwise, this will throw an exception on resolving the default identifier InvalidTcaSchemaException. Using the raw TCA configuration is furthermore not recommended and only available to support FlexFormTools during schema building. For extensions this might be the case on using BeforeTcaOverridesEvent or AfterTcaCompilationEvent.

Tags

throws
RuntimeException

If TCA is misconfigured

throws
InvalidTcaException

Return values

string —

Identifier JSON string

parseDataStructureByIdentifier()

Parse a data structure identified by $identifier to the final data structure array.

public parseDataStructureByIdentifier(string $identifier[, array|TcaSchema|null $schema = null ]) : array

This method is called after getDataStructureIdentifier(), finds the data structure and returns it.

Events allow to manipulate the find logic and to post process the data structure array.

Important: The TCA for data structure definitions MUST be overridden by 'columnsOverrides' as the "ds" config is a string, containing the data structure or a file pointer.

After the data structure definition is found, the method resolves:

  • FILE:EXT: prefix of the data structure itself - the ds is in a file
  • FILE:EXT: prefix for sheets - if single sheets are in files
  • Create a sDEF sheet if the data structure has non, yet.
  • TCA Migration and Preparation is done for the resolved fields

After that method is run, the data structure is fully resolved to an array, and same base normalization is done: If the ds did not contain a sheet, it will have one afterward as "sDEF".

This method gets: Target specification of the data structure. This method returns: The normalized data structure parsed to an array.

Parameters

$identifier : string

JSON string to find the data structure location

$schema : array|TcaSchema|null = null

Either be the Tca Schema object or raw TCA configuration. Only omit in case handling is done via events. Otherwise, this will throw an exception on resolving the default identifier InvalidTcaSchemaException. Using the raw TCA configuration is furthermore not recommended and only available to support FlexFormTools during schema building. For extensions this might be the case on using BeforeTcaOverridesEvent or AfterTcaCompilationEvent.

Tags

throws
InvalidIdentifierException
throws
InvalidTcaSchemaException
throws
InvalidDataStructureException

Return values

array —

Parsed and normalized data structure

convertDataStructureToArray()

protected convertDataStructureToArray(string|array $dataStructure) : array

Parameters

$dataStructure : string|array

Return values

array

ensureDefaultSheet()

Ensures a data structure has a default sheet, and no duplicate data

protected ensureDefaultSheet(array $dataStructure) : array

Parameters

$dataStructure : array

Return values

array

getDefaultDataStructureIdentifier()

Finds data structure in TCA, defined in column config 'ds'

protected getDefaultDataStructureIdentifier(string $tableName, string $fieldName, array $row[, array|TcaSchema|null $schema = null ]) : array

fieldTca = [ 'config' => [ 'type' => 'flex', 'ds' => '<T3DataStructure>...' OR 'FILE:...', ] ]

This method returns an array of the form: [ 'type' => 'tca', 'tableName' => $tableName, 'fieldName' => $fieldName, 'dataStructureKey' => $key, ];

Example: [ 'type' => 'tca', 'tableName' => 'tt_content', 'fieldName' => 'pi_flexform', 'dataStructureKey' => 'default', ];

In case the TCA table supports record types and the given $row uses a record type with a custom data structure (via columnsOverrides) the record type is used as "dataStructureKey".

Example: [ 'type' => 'tca', 'tableName' => 'tt_content', 'fieldName' => 'pi_flexform', 'dataStructureKey' => 'powermail_pi1', ];

Parameters

$tableName : string
$fieldName : string
$row : array
$schema : array|TcaSchema|null = null

Tags

throws
InvalidTcaException
throws
InvalidTcaSchemaException

Return values

array —

Identifier as array, see example above

getDefaultStructureForIdentifier()

Finds and returns the data structure from TCA - defined in column config 'ds'

protected getDefaultStructureForIdentifier(array $identifier[, array|TcaSchema|null $schema = null ]) : string

fieldTca = [ 'config' => [ 'type' => 'flex', 'ds' => '<T3DataStructure>...' OR 'FILE:...', ] ]

Based on an identifier, e.g.: [ 'type' => 'tca', 'tableName' => 'tt_content', 'fieldName' => 'pi_flexform', 'dataStructureKey' => 'default', ];

this method returns '<T3DataStructure>...' OR 'FILE:...'.

In case the TCA table supports record types and the "dataStructureKey" points to a record type, which is only the case if a record type defines a custom flex config (via columnsOverrides), this custom data structure is returned.

Parameters

$identifier : array
$schema : array|TcaSchema|null = null

Tags

throws
InvalidTcaSchemaException

Return values

string —

resolved data structure

getRecordTypeSpecificFieldConfig()

Returns the record type specific configuration, also already taking columnsOverrides into account.

protected getRecordTypeSpecificFieldConfig(array $tcaForTable, string $recordType, string $fieldName) : array

In case the field is not defined for the record type, no configuration is returned.

Parameters

$tcaForTable : array
$recordType : string
$fieldName : string

Return values

array

resolveFileDirectives()

Resolve FILE:EXT and EXT: for single sheets

protected resolveFileDirectives(array $dataStructure) : array

Parameters

$dataStructure : array

Return values

array
On this page