FlexFormTools

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

Service class to help with TCA type="flex" details.

This service provides various helpers to determine the data structure of flex form fields and to maintain integrity of flex form related details in general.

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.
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
getDataStructureIdentifierFromTcaArray()  : array
Find matching data structure in TCA ds array.
getDefaultIdentifier()  : array
Returns the default data structure identifier.
getDefaultStructureForIdentifier()  : string
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) : string

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

Parameters

$table : string
$field : string
$row : array

Return values

string

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) : 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 getFlexFormDataStructureByIdentifier() 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 NOT be overridden by 'columnsOverrides' or by parent TCA in an inline relation! This would create a huge mess.

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

Tags

throws
RuntimeException

If TCA is misconfigured

throws
InvalidCombinedPointerFieldException
throws
InvalidSinglePointerFieldException
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

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

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

Important: The TCA for data structure definitions MUST NOT be overridden by 'columnsOverrides' or by parent TCA in an inline relation! This would create a huge mess.

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.

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.

Read the unit tests for nasty details.

Parameters

$identifier : string

JSON string to find the data structure location

Tags

throws
InvalidIdentifierException

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

getDataStructureIdentifierFromTcaArray()

Find matching data structure in TCA ds array.

protected getDataStructureIdentifierFromTcaArray(array $fieldTca, string $tableName, string $fieldName, array $row) : array

Data structure is defined in 'ds' config array, optionally with 'ds_pointerField'.

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

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' => 'powermail_pi1,list', ];

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

Tags

throws
InvalidCombinedPointerFieldException
throws
InvalidSinglePointerFieldException
throws
InvalidTcaException

Return values

array —

Identifier as array, see example above

getDefaultIdentifier()

Returns the default data structure identifier.

protected getDefaultIdentifier(array $fieldTca, string $tableName, string $fieldName, array $row) : array

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

Tags

throws
InvalidCombinedPointerFieldException
throws
InvalidSinglePointerFieldException
throws
InvalidTcaException

Return values

array

getDefaultStructureForIdentifier()

protected getDefaultStructureForIdentifier(array $identifier) : string

Parameters

$identifier : array

Return values

string

resolveFileDirectives()

Resolve FILE:EXT and EXT: for single sheets

protected resolveFileDirectives(array $dataStructure) : array

Parameters

$dataStructure : array

Return values

array
On this page