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.
- 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<string|int, mixed>
- Parse a data structure identified by $identifier to the final data structure array.
- convertDataStructureToArray() : array<string|int, mixed>
- ensureDefaultSheet() : array<string|int, mixed>
- Ensures a data structure has a default sheet, and no duplicate data
- getDefaultDataStructureIdentifier() : array<string|int, mixed>
- 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<string|int, mixed>
- Returns the record type specific configuration, also already taking columnsOverrides into account.
- resolveFileDirectives() : array<string|int, mixed>
- Resolve FILE:EXT and EXT: for single sheets
Methods
__construct()
public
__construct(EventDispatcherInterface $eventDispatcher, TcaMigration $tcaMigration, TcaPreparation $tcaPreparation) : mixed
Parameters
- $eventDispatcher : EventDispatcherInterface
- $tcaMigration : TcaMigration
- $tcaPreparation : TcaPreparation
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<string|int, mixed> $row, array<string|int, mixed>|TcaSchema $schema) : string
The order of tags will follow that of the data structure.
Parameters
- $table : string
- $field : string
- $row : array<string|int, mixed>
- $schema : array<string|int, mixed>|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.
Signature may change, for instance to split 'DS finding' and flexArray2Xml(), which would allow broader use of the method. It is currently consumed by cleanup:flexforms CLI only.
Return values
stringflexArray2Xml()
Convert FlexForm data array to XML
public
flexArray2Xml(array<string|int, mixed> $array) : string
Parameters
- $array : array<string|int, mixed>
Return values
stringgetDataStructureIdentifier()
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<string|int, mixed> $fieldTca, string $tableName, string $fieldName, array<string|int, mixed> $row[, array<string|int, mixed>|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<string|int, mixed>
-
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<string|int, mixed>
-
The data row
- $schema : array<string|int, mixed>|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
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<string|int, mixed>|TcaSchema|null $schema = null ]) : array<string|int, mixed>
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<string|int, mixed>|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
Return values
array<string|int, mixed> —Parsed and normalized data structure
convertDataStructureToArray()
protected
convertDataStructureToArray(string|array<string|int, mixed> $dataStructure) : array<string|int, mixed>
Parameters
- $dataStructure : string|array<string|int, mixed>
Return values
array<string|int, mixed>ensureDefaultSheet()
Ensures a data structure has a default sheet, and no duplicate data
protected
ensureDefaultSheet(array<string|int, mixed> $dataStructure) : array<string|int, mixed>
Parameters
- $dataStructure : array<string|int, mixed>
Return values
array<string|int, mixed>getDefaultDataStructureIdentifier()
Finds data structure in TCA, defined in column config 'ds'
protected
getDefaultDataStructureIdentifier(string $tableName, string $fieldName, array<string|int, mixed> $row[, array<string|int, mixed>|TcaSchema|null $schema = null ]) : array<string|int, mixed>
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<string|int, mixed>
- $schema : array<string|int, mixed>|TcaSchema|null = null
Tags
Return values
array<string|int, mixed> —Identifier as array, see example above
getDefaultStructureForIdentifier()
Finds and returns the data structure from TCA - defined in column config 'ds'
protected
getDefaultStructureForIdentifier(array<string|int, mixed> $identifier[, array<string|int, mixed>|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<string|int, mixed>
- $schema : array<string|int, mixed>|TcaSchema|null = null
Tags
Return values
string —resolved data structure
getRecordTypeSpecificFieldConfig()
Returns the record type specific configuration, also already taking columnsOverrides into account.
protected
getRecordTypeSpecificFieldConfig(array<string|int, mixed> $tcaForTable, string $recordType, string $fieldName) : array<string|int, mixed>
In case the field is not defined for the record type, no configuration is returned.
Parameters
- $tcaForTable : array<string|int, mixed>
- $recordType : string
- $fieldName : string
Return values
array<string|int, mixed>resolveFileDirectives()
Resolve FILE:EXT and EXT: for single sheets
protected
resolveFileDirectives(array<string|int, mixed> $dataStructure) : array<string|int, mixed>
Parameters
- $dataStructure : array<string|int, mixed>