TYPO3 12.4 API: RelationHandler

RelationHandler

Load database groups (relations) Used to process the relations created by the TCA element types "group" and "select" for database records.

Manages MM-relations as well.

Properties

$additionalWhere : array<string|int, mixed>
$checkIfDeleted : bool: Deleted-column is added to additionalWhere... if this is set.
$itemArray : array<int, array<string, mixed>>: Contains items in a numeric array (table/id for each). Tablenames here might be "_NO_TABLE". Keeps the sorting of thee retrieved items.
$nonTableArray : array<string|int, mixed>: Array for NON-table elements
$registerNonTableValues : bool: If set, values that are not ids in tables are normally discarded. By this options they will be preserved.
$results : array<string|int, mixed>: This array will be filled by getFromDB().
$tableArray : array<string|int, mixed>: Contains the table names as keys. The values are the id-values for each table.
$undeleteRecord : bool: If a record should be undeleted (so do not use the $useDeleteClause on \TYPO3\CMS\Backend\Utility\BackendUtility)
$currentTable : string: Current table => Only needed for reverse relations
$fetchAllFields : bool: $fetchAllFields if false getFromDB() fetches only uid, pid, thumbnail and label fields (as defined in TCA)
$firstTable : string: Will contain the first table name in the $tablelist (for positive ids)
$MM_hasUidField : bool: This is set to TRUE if the MM table has a UID field.
$MM_insert_fields : array<string|int, mixed>: Array of fields and value pairs used for insert in MM table
$MM_is_foreign : bool: If TRUE, uid_local and uid_foreign are switched, and the current table is inserted as tablename - this means you display a foreign relation "from the opposite side"
$MM_isMultiTableRelationship : string: Is empty by default; if MM_is_foreign is set and there is more than one table allowed (on the "local" side), then it contains the first table (as a fallback)
$MM_match_fields : array<string|int, mixed>: Array of fields value pairs that should match while SELECT.
$MM_oppositeUsage : array<string|int, mixed>: Usage of an MM field on the opposite relation.
$MM_table_where : string: Extra MM table where
$purged : bool
$referenceIndexUpdater : ReferenceIndexUpdater|null
$useLiveParentIds : bool
$useLiveReferenceIds : bool
$workspaceId : int|null

Methods

convertItemArray() : bool: Converts elements in the local item array to use version ids instead of live ids, if possible. The most common use case is, to call that prior to processing with MM relations in a workspace context. For tha special case, ids on both side of the MM relation must use version ids if available.
countItems() : mixed: Counts the items in $this->itemArray and puts this value in an array by default.
getFromDB() : array<string|int, mixed>: Reads all records from internal tableArray into the internal ->results array where keys are table names and for each table, records are stored with uids as their keys.
getResolvedItemArray() : array<string|int, mixed>: This method is typically called after getFromDB().
getValueArray() : array<string|int, mixed>: After initialization you can extract an array of the elements from the object. Use this function for that.
isPurged() : bool: Whether item array has been purged in this instance.
processDeletePlaceholder() : bool: Removes items having a delete placeholder from $this->itemArray
purgeItemArray() : bool
setFetchAllFields() : mixed: Sets $fetchAllFields
setReferenceIndexUpdater() : void: Setter to carry the 'deferred' reference index updater registry around.
setUseLiveParentIds() : mixed
setUseLiveReferenceIds() : mixed
setWorkspaceId() : void: Sets the current workspace id.
start() : mixed: Initialization of the class.
writeForeignField() : mixed: Write the sorting values to a foreign_table, that has a foreign_field (uid of the parent record)
writeMM() : mixed: Writes the internal itemArray to MM table:
completeOppositeUsageValues() : array<string|int, mixed>: Completes MM values to be written by values from the opposite relation.
getConnectionForTableName() : Connection
getLiveDefaultId() : int: Gets the record uid of the live default record. If already pointing to the live record, the submitted record uid is returned.
getResolver() : PlainDataResolver
getWorkspaceId() : int: Gets the current workspace id.
isOnSymmetricSide() : bool: Checks, if we're looking from the "other" side, the symmetric side, to a symmetric relation.
purgeDeletePlaceholder() : array<string|int, mixed>: Purges ids that have a delete placeholder
purgeItemArrayHandler() : bool: Handles a purge callback on $this->itemArray
purgeLiveVersionedIds() : array<string|int, mixed>: Clean up the list of incoming MM connection candidates.
purgeVersionedIds() : array<string|int, mixed>: Purges ids that are versioned.
readForeignField() : mixed: Reads items from a foreign_table, that has a foreign_field (uid of the parent record) and stores the parts in the internal array itemArray and tableArray.
readList() : mixed: Explodes the item list and stores the parts in the internal arrays itemArray and tableArray from MM records.
readMM() : mixed: Reads the record tablename/id into the internal arrays itemArray and tableArray from MM records.
removeFromItemArray() : mixed
sanitizeIds() : array<string|int, mixed>: Removes empty values (null, '0', 0, false).
sortList() : mixed: Does a sorting on $this->itemArray depending on a default sortby field.
updateRefIndex() : array<string|int, mixed>: Update Reference Index (sys_refindex) for a record.

$additionalWhere


    public
        array<string|int, mixed>
    $additionalWhere
     = []

$checkIfDeleted

Deleted-column is added to additionalWhere... if this is set.


    public
        bool
    $checkIfDeleted
     = true

$itemArray

Contains items in a numeric array (table/id for each). Tablenames here might be "_NO_TABLE". Keeps the sorting of thee retrieved items.


    public
        array<int, array<string, mixed>>
    $itemArray
     = []

$nonTableArray

Array for NON-table elements


    public
        array<string|int, mixed>
    $nonTableArray
     = []

$registerNonTableValues

If set, values that are not ids in tables are normally discarded. By this options they will be preserved.


    public
        bool
    $registerNonTableValues
     = false

$results

This array will be filled by getFromDB().


    public
        array<string|int, mixed>
    $results
     = []

$tableArray

Contains the table names as keys. The values are the id-values for each table.


    public
        array<string|int, mixed>
    $tableArray
     = []

Should ONLY contain proper table names.

$undeleteRecord

If a record should be undeleted (so do not use the $useDeleteClause on \TYPO3\CMS\Backend\Utility\BackendUtility)


    public
        bool
    $undeleteRecord

$currentTable

Current table => Only needed for reverse relations


    protected
        string
    $currentTable

$fetchAllFields

$fetchAllFields if false getFromDB() fetches only uid, pid, thumbnail and label fields (as defined in TCA)


    protected
        bool
    $fetchAllFields
     = true

$firstTable

Will contain the first table name in the $tablelist (for positive ids)


    protected
        string
    $firstTable
     = ''

$MM_hasUidField

This is set to TRUE if the MM table has a UID field.


    protected
        bool
    $MM_hasUidField

$MM_insert_fields

Array of fields and value pairs used for insert in MM table

Deprecated

since v12. Remove in v13 with other MM_insert_fields places.


    protected
        array<string|int, mixed>
    $MM_insert_fields
     = []

$MM_is_foreign

If TRUE, uid_local and uid_foreign are switched, and the current table is inserted as tablename - this means you display a foreign relation "from the opposite side"


    protected
        bool
    $MM_is_foreign
     = false

$MM_isMultiTableRelationship

Is empty by default; if MM_is_foreign is set and there is more than one table allowed (on the "local" side), then it contains the first table (as a fallback)


    protected
        string
    $MM_isMultiTableRelationship
     = ''

$MM_match_fields

Array of fields value pairs that should match while SELECT.


    protected
        array<string|int, mixed>
    $MM_match_fields
     = []

$MM_oppositeUsage

Usage of an MM field on the opposite relation.


    protected
        array<string|int, mixed>
    $MM_oppositeUsage

$MM_table_where

Extra MM table where


    protected
        string
    $MM_table_where
     = ''

$purged


    protected
        bool
    $purged
     = false

$referenceIndexUpdater


    protected
        ReferenceIndexUpdater|null
    $referenceIndexUpdater

$useLiveParentIds


    protected
        bool
    $useLiveParentIds
     = true

$useLiveReferenceIds


    protected
        bool
    $useLiveReferenceIds
     = true

$workspaceId


    protected
        int|null
    $workspaceId

convertItemArray()

Converts elements in the local item array to use version ids instead of live ids, if possible. The most common use case is, to call that prior to processing with MM relations in a workspace context. For tha special case, ids on both side of the MM relation must use version ids if available.


    public
                    convertItemArray() : bool

Return values

bool —

Whether items have been converted

countItems()

Counts the items in $this->itemArray and puts this value in an array by default.


    public
                    countItems([bool $returnAsArray = true ]) : mixed

Parameters

$returnAsArray : bool = true: Whether to put the count value in an array

Return values

mixed —

The plain count as integer or the same inside an array

getFromDB()

Reads all records from internal tableArray into the internal ->results array where keys are table names and for each table, records are stored with uids as their keys.


    public
                    getFromDB() : array<string|int, mixed>

If $this->fetchAllFields is false you can save a little memory since only uid,pid and a few other fields are selected.

Return values

array<string|int, mixed>

getResolvedItemArray()

This method is typically called after getFromDB().


    public
                    getResolvedItemArray() : array<string|int, mixed>

$this->results holds a list of resolved and valid relations, $this->itemArray hold a list of "selected" relations from the incoming selection array. The difference is that "itemArray" may hold a single table/uid combination multiple times, for instance in a type=group relation having multiple=true, while "results" hold each resolved relation only once. The methods creates a sanitized "itemArray" from resolved "results" list, normalized the return array to always contain both table name and uid, and keep incoming "itemArray" sort order and keeps "multiple" selections.

In addition, the item array contains the full record to be used later-on and save database queries. This method keeps the ordering intact.

Return values

array<string|int, mixed>

getValueArray()

After initialization you can extract an array of the elements from the object. Use this function for that.


    public
                    getValueArray([bool $prependTableName = false ]) : array<string|int, mixed>

Parameters

$prependTableName : bool = false: If set, then table names will ALWAYS be prepended (unless its a _NO_TABLE value)

Return values

array<string|int, mixed> —

A numeric array.

isPurged()

Whether item array has been purged in this instance.


    public
                    isPurged() : bool

Return values

bool

processDeletePlaceholder()

Removes items having a delete placeholder from $this->itemArray


    public
                    processDeletePlaceholder() : bool

Return values

bool —

Whether items have been purged

purgeItemArray()


    public
                    purgeItemArray([int|null $workspaceId = null ]) : bool

Parameters

$workspaceId : int|null = null

Internal

Return values

bool —

Whether items have been purged

setFetchAllFields()

Sets $fetchAllFields


    public
                    setFetchAllFields(bool $allFields) : mixed

Parameters

$allFields : bool: enables fetching of all fields in getFromDB()

setReferenceIndexUpdater()

Setter to carry the 'deferred' reference index updater registry around.


    public
                    setReferenceIndexUpdater(ReferenceIndexUpdater $updater) : void

Parameters

$updater : ReferenceIndexUpdater

Internal

Used internally within DataHandler only

setUseLiveParentIds()


    public
                    setUseLiveParentIds(bool $useLiveParentIds) : mixed

Parameters

$useLiveParentIds : bool

setUseLiveReferenceIds()


    public
                    setUseLiveReferenceIds(bool $useLiveReferenceIds) : mixed

Parameters

$useLiveReferenceIds : bool

setWorkspaceId()

Sets the current workspace id.


    public
                    setWorkspaceId(int $workspaceId) : void

Parameters

$workspaceId : int

start()

Initialization of the class.


    public
                    start(string $itemlist, string $tablelist[, string $MMtable = '' ][, int|string $MMuid = 0 ][, string $currentTable = '' ][, array<string|int, mixed> $conf = [] ]) : mixed

Parameters

$itemlist : string: List of group/select items
$tablelist : string: Comma list of tables, first table takes priority if no table is set for an entry in the list.
$MMtable : string = '': Name of a MM table.
$MMuid : int|string = 0: Local UID for MM lookup. May be a string for newly created elements.
$currentTable : string = '': Current table name
$conf : array<string|int, mixed> = []: TCA configuration for current field

writeForeignField()

Write the sorting values to a foreign_table, that has a foreign_field (uid of the parent record)


    public
                    writeForeignField(array<string|int, mixed> $conf, int $parentUid[, int $updateToUid = 0 ]) : mixed

Parameters

$conf : array<string|int, mixed>: TCA configuration for current field
$parentUid : int: The uid of the parent record
$updateToUid : int = 0: If this is larger than zero it will be used as foreign UID instead of the given $parentUid (on Copy)

writeMM()

Writes the internal itemArray to MM table:


    public
                    writeMM(string $MM_tableName, int $uid[, bool $prependTableName = false ]) : mixed

Parameters

$MM_tableName : string: MM table name
$uid : int: Local UID
$prependTableName : bool = false: If set, then table names will always be written.

completeOppositeUsageValues()

Completes MM values to be written by values from the opposite relation.


    protected
                    completeOppositeUsageValues(string $tableName, array<string|int, mixed> $referenceValues) : array<string|int, mixed>

This method used MM insert field or MM match fields if defined.

Parameters

$tableName : string: Name of the opposite table
$referenceValues : array<string|int, mixed>: Values to be written

Return values

array<string|int, mixed> —

Values to be written, possibly modified

getConnectionForTableName()


    protected
                    getConnectionForTableName(string $tableName) : Connection

Parameters

$tableName : string

Return values

Connection

getLiveDefaultId()

Gets the record uid of the live default record. If already pointing to the live record, the submitted record uid is returned.


    protected
                    getLiveDefaultId(string $tableName, int|string $id) : int

Parameters

$tableName : string
$id : int|string

Return values

int

getResolver()


    protected
                    getResolver(string $tableName, array<string|int, int> $ids[, array<string|int, mixed>|null $sortingStatement = null ]) : PlainDataResolver

Parameters

$tableName : string
$ids : array<string|int, int>
$sortingStatement : array<string|int, mixed>|null = null

Return values

PlainDataResolver

getWorkspaceId()

Gets the current workspace id.


    protected
                    getWorkspaceId() : int

Return values

int

isOnSymmetricSide()

Checks, if we're looking from the "other" side, the symmetric side, to a symmetric relation.


    protected
            static        isOnSymmetricSide(string $parentUid, array<string|int, mixed> $parentConf, array<string|int, mixed> $childRec) : bool

Parameters

$parentUid : string: The uid of the parent record
$parentConf : array<string|int, mixed>: The TCA configuration of the parent field embedding the child records
$childRec : array<string|int, mixed>: The record row of the child record

Return values

bool —

Returns TRUE if looking from the symmetric ("other") side to the relation.

purgeDeletePlaceholder()

Purges ids that have a delete placeholder


    protected
                    purgeDeletePlaceholder(string $tableName, array<string|int, mixed> $ids) : array<string|int, mixed>

Parameters

$tableName : string
$ids : array<string|int, mixed>

Return values

array<string|int, mixed>

purgeItemArrayHandler()

Handles a purge callback on $this->itemArray


    protected
                    purgeItemArrayHandler(string $purgeCallback, int $workspaceId) : bool

Parameters

$purgeCallback : string
$workspaceId : int

Return values

bool —

Whether items have been purged

purgeLiveVersionedIds()

Clean up the list of incoming MM connection candidates.


    protected
                    purgeLiveVersionedIds(string $tableName, array<string|int, mixed> $candidateUidList, int $targetWorkspaceUid) : array<string|int, mixed>

readMM() results in a uid list that contains:

uids of all live MM connections
uids of workspace connections of all workspaces The method filters this candidate list:
Remove candidates of different workspaces
Remove live candidates that do have a workspace overlay

Parameters

$tableName : string
$candidateUidList : array<string|int, mixed>
$targetWorkspaceUid : int

Return values

array<string|int, mixed>

purgeVersionedIds()

Purges ids that are versioned.


    protected
                    purgeVersionedIds(string $tableName, array<string|int, mixed> $ids) : array<string|int, mixed>

Parameters

$tableName : string
$ids : array<string|int, mixed>

Return values

array<string|int, mixed>

readForeignField()

Reads items from a foreign_table, that has a foreign_field (uid of the parent record) and stores the parts in the internal array itemArray and tableArray.


    protected
                    readForeignField(int|string $uid, array<string|int, mixed> $conf) : mixed

Parameters

$uid : int|string: The uid of the parent record (this value is also on the foreign_table in the foreign_field)
$conf : array<string|int, mixed>: TCA configuration for current field

readList()

Explodes the item list and stores the parts in the internal arrays itemArray and tableArray from MM records.


    protected
                    readList(string $itemlist, array<string|int, mixed> $configuration) : mixed

Parameters

$itemlist : string: Item list
$configuration : array<string|int, mixed>: Parent field configuration

readMM()

Reads the record tablename/id into the internal arrays itemArray and tableArray from MM records.


    protected
                    readMM(string $tableName, int|string $uid, string $mmOppositeTable) : mixed

Parameters

$tableName : string: MM Tablename
$uid : int|string: Local UID
$mmOppositeTable : string: Opposite table name

removeFromItemArray()


    protected
                    removeFromItemArray(mixed $tableName, mixed $id) : mixed

Parameters

$tableName : mixed
$id : mixed

sanitizeIds()

Removes empty values (null, '0', 0, false).


    protected
                    sanitizeIds(array<string|int, int> $ids) : array<string|int, mixed>

Parameters

$ids : array<string|int, int>

Return values

array<string|int, mixed>

sortList()

Does a sorting on $this->itemArray depending on a default sortby field.


    protected
                    sortList(string $sortby) : mixed

This is only used for automatic sorting of comma separated lists. This function is only relevant for data that is stored in comma separated lists!

Parameters

$sortby : string: The default_sortby field/command (e.g. 'price DESC')

updateRefIndex()

Update Reference Index (sys_refindex) for a record.


    protected
                    updateRefIndex(string $table, int $uid) : array<string|int, mixed>

Should be called any almost any update to a record which could affect references inside the record. If used from within DataHandler, only registers a row for update for later processing.

Parameters

$table : string: Table name
$uid : int: Record uid

Return values

array<string|int, mixed> —

Empty array

RelationHandler

Table of Contents

Properties

Methods

Properties

$additionalWhere

$checkIfDeleted

$itemArray

$nonTableArray

$registerNonTableValues

$results

$tableArray

$undeleteRecord

$currentTable

$fetchAllFields

$firstTable

$MM_hasUidField

$MM_insert_fields

$MM_is_foreign

$MM_isMultiTableRelationship

$MM_match_fields

$MM_oppositeUsage

$MM_table_where

$purged

$referenceIndexUpdater

$useLiveParentIds

$useLiveReferenceIds

$workspaceId

Methods

convertItemArray()

Return values

countItems()

Parameters

Return values

getFromDB()

Return values

getResolvedItemArray()

Return values

getValueArray()

Parameters

Return values

isPurged()

Return values

processDeletePlaceholder()

Return values

purgeItemArray()

Parameters

Tags

Return values

setFetchAllFields()

Parameters

setReferenceIndexUpdater()

Parameters

setUseLiveParentIds()

Parameters

setUseLiveReferenceIds()

Parameters

setWorkspaceId()

Parameters

start()

Parameters

writeForeignField()

Parameters

writeMM()

Parameters

completeOppositeUsageValues()

Parameters

Return values

getConnectionForTableName()

Parameters

Return values

getLiveDefaultId()

Parameters

Return values

getResolver()

Parameters

Return values

getWorkspaceId()

Return values

isOnSymmetricSide()