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.

Table of Contents

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 and will be written into MM table if $MM_insert_fields is not set
$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
$updateReferenceIndex  : bool
If false, reference index is not updated.
$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
remapMM()  : mixed
Remaps MM table elements from one local uid to another Does NOT update the reference index for you, must be called subsequently to do that!
setFetchAllFields()  : mixed
Sets $fetchAllFields
setReferenceIndexUpdater()  : void
Setter to carry the 'deferred' reference index updater registry around.
setUpdateReferenceIndex()  : mixed
Sets whether the reference index shall be updated.
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>
Purges ids that are live but have an accordant version.
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.

Properties

$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

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 and will be written into MM table if $MM_insert_fields is not set

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 = ''

$updateReferenceIndex

If false, reference index is not updated.

Deprecated

since v11, will be removed in v12

protected bool $updateReferenceIndex = true

$useLiveParentIds

protected bool $useLiveParentIds = true

$useLiveReferenceIds

protected bool $useLiveReferenceIds = true

$workspaceId

protected int|null $workspaceId

Methods

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
Tags
todo:

It should be possible to drop all three 'purge' methods by using a clever join within readMM - that sounds doable now with pid -1 and ws-pair records being gone since v11. It would resolve this indirect callback logic and would reduce some queries. The (workspace) mm tests should be complete enough now to verify if a change like that would do.

Return values
bool —

Whether items have been purged

remapMM()

Remaps MM table elements from one local uid to another Does NOT update the reference index for you, must be called subsequently to do that!

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

since v11, will be removed with v12.

Parameters
$MM_tableName : string

MM table name

$uid : int

Local, current UID

$newUid : int

Local, new UID

$prependTableName : bool = false

If set, then table names will always be written.

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

setUpdateReferenceIndex()

Sets whether the reference index shall be updated.

public setUpdateReferenceIndex(bool $updateReferenceIndex) : mixed
Deprecated

since v11, will be removed in v12

Parameters
$updateReferenceIndex : bool

Whether the reference index shall be updated

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 ][, bool $skipSorting = null ]) : 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)

$skipSorting : bool = null

@deprecated since v11, will be dropped with v12. Simplify the if below when removing argument.

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) : bool
Parameters
$purgeCallback : string
Return values
bool —

Whether items have been purged

purgeLiveVersionedIds()

Purges ids that are live but have an accordant version.

protected purgeLiveVersionedIds(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>

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

Tags
todo:

The source record is not checked for correct workspace. Say there is a category 5 in workspace 1. setWorkspace(0) is called, after that readMM('sys_category_record_mm', 5 ...). readMM will still return the list of records connected to this workspace 1 item, even though workspace 0 has been set.

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> —

Result from ReferenceIndex->updateRefIndexTable() updated directly, else empty array


        

        
    




    

    

                            

            

                            
    

        On this page

        
    


            

                    

        

    

        

            
Search results