‪TYPO3CMS  ‪main
TYPO3\CMS\Core\Database\RelationHandler Class Reference

Public Member Functions

 setWorkspaceId ($workspaceId)
 setReferenceIndexUpdater (ReferenceIndexUpdater $updater)
bool isPurged ()
 start ($itemlist, $tablelist, $MMtable='', $MMuid=0, $currentTable='', $conf=[])
 setUseLiveParentIds ($useLiveParentIds)
 setUseLiveReferenceIds ($useLiveReferenceIds)
 writeMM ($MM_tableName, $uid, $prependTableName=false)
 writeForeignField ($conf, $parentUid, $updateToUid=0)
array getValueArray ($prependTableName=false)
array getFromDB ()
 getResolvedItemArray ()
mixed countItems ($returnAsArray=true)
bool convertItemArray ()
bool purgeItemArray ($workspaceId=null)
bool processDeletePlaceholder ()

Public Attributes

bool $registerNonTableValues = false
array $tableArray = array( )
array< int, $itemArray=array();public array $nonTableArray=array();public array $additionalWhere=array();public bool $checkIfDeleted=true;protected string $firstTable='';protected bool $MM_is_foreign=false;protected string $MM_isMultiTableRelationship='';protected string $currentTable;public bool $undeleteRecord;protected array $MM_match_fields=[];protected bool $multiple=false;protected string $MM_table_where='';protected array $MM_oppositeUsage;protected ReferenceIndexUpdater|null $referenceIndexUpdater;protected bool $useLiveParentIds=true;protected bool $useLiveReferenceIds=true;protected int|null $workspaceId;protected bool $purged=false;public array $results=array();protected function getWorkspaceId():int { $backendUser=$GLOBALS[ 'BE_USER'] ?? null;if(!isset( $this->workspaceId)) { $this-> workspaceId = $backendUser instanceof BackendUserAuthentication ? (int)($backendUser->workspace) : 0
return $this workspaceId

Protected Member Functions

 readList ($itemlist, array $configuration)
 sortList ($sortby)
 readMM ($tableName, $uid, $mmOppositeTable)
 readForeignField ($uid, $conf)
array updateRefIndex ($table, $uid)
bool purgeItemArrayHandler ($purgeCallback)
array purgeVersionedIds ($tableName, array $ids)
array purgeLiveVersionedIds ($tableName, array $ids)
array purgeDeletePlaceholder ($tableName, array $ids)
 removeFromItemArray ($tableName, $id)
array completeOppositeUsageValues ($tableName, array $referenceValues)
int getLiveDefaultId ($tableName, $id)
 sanitizeIds (array $ids)
PlainDataResolver getResolver ($tableName, array $ids, array $sortingStatement=null)
Connection getConnectionForTableName (string $tableName)

Static Protected Member Functions

static bool isOnSymmetricSide ($parentUid, $parentConf, $childRec)

Detailed Description

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.

Definition at line 35 of file RelationHandler.php.

Member Function Documentation

◆ completeOppositeUsageValues()

array TYPO3\CMS\Core\Database\RelationHandler::completeOppositeUsageValues (   $tableName,
array  $referenceValues 

Completes MM values to be written by values from the opposite relation. This method used MM insert field or MM match fields if defined.

string$tableName‪Name of the opposite table
array$referenceValues‪Values to be written
‪array Values to be written, possibly modified

Definition at line 1464 of file RelationHandler.php.

References $GLOBALS.

Referenced by TYPO3\CMS\Core\Database\RelationHandler\writeMM().

◆ convertItemArray()

bool TYPO3\CMS\Core\Database\RelationHandler::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.

‪bool Whether items have been converted

Definition at line 1171 of file RelationHandler.php.

References TYPO3\CMS\Core\Database\RelationHandler\getResolver(), TYPO3\CMS\Core\DataHandling\PlainDataResolver\processVersionOverlays(), TYPO3\CMS\Core\DataHandling\PlainDataResolver\setKeepDeletePlaceholder(), and TYPO3\CMS\Core\DataHandling\PlainDataResolver\setKeepMovePlaceholder().

◆ countItems()

mixed TYPO3\CMS\Core\Database\RelationHandler::countItems (   $returnAsArray = true)

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

bool$returnAsArray‪Whether to put the count value in an array
‪mixed The plain count as integer or the same inside an array

Definition at line 1135 of file RelationHandler.php.

◆ getConnectionForTableName()

◆ getFromDB()

array TYPO3\CMS\Core\Database\RelationHandler::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.


Definition at line 1068 of file RelationHandler.php.

References TYPO3\CMS\Core\Database\RelationHandler\getConnectionForTableName(), TYPO3\CMS\Core\Database\Platform\PlatformInformation\getMaxBindParameters(), and TYPO3\CMS\Core\Database\Query\QueryHelper\stripLogicalOperatorPrefix().

◆ getLiveDefaultId()

int TYPO3\CMS\Core\Database\RelationHandler::getLiveDefaultId (   $tableName,

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

int | string$id

Definition at line 1511 of file RelationHandler.php.

Referenced by TYPO3\CMS\Core\Database\RelationHandler\readForeignField(), TYPO3\CMS\Core\Database\RelationHandler\readList(), and TYPO3\CMS\Core\Database\RelationHandler\writeForeignField().

◆ getResolvedItemArray()

TYPO3\CMS\Core\Database\RelationHandler::getResolvedItemArray ( )

This method is typically called after getFromDB(). $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 method 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.

Definition at line 1114 of file RelationHandler.php.

◆ getResolver()

PlainDataResolver TYPO3\CMS\Core\Database\RelationHandler::getResolver (   $tableName,
array  $ids,
array  $sortingStatement = null 

◆ getValueArray()

array TYPO3\CMS\Core\Database\RelationHandler::getValueArray (   $prependTableName = false)

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

bool$prependTableName‪If set, then table names will ALWAYS be prepended (unless its a _NO_TABLE value)
‪array A numeric array.

Definition at line 1044 of file RelationHandler.php.

◆ isOnSymmetricSide()

static bool TYPO3\CMS\Core\Database\RelationHandler::isOnSymmetricSide (   $parentUid,

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

string$parentUid‪The uid of the parent record
array$parentConf‪The TCA configuration of the parent field embedding the child records
array$childRec‪The record row of the child record
‪bool Returns TRUE if looking from the symmetric ("other") side to the relation.

Definition at line 1449 of file RelationHandler.php.

References TYPO3\CMS\Core\Utility\MathUtility\canBeInterpretedAsInteger().

Referenced by TYPO3\CMS\Core\Database\RelationHandler\writeForeignField().

◆ isPurged()

bool TYPO3\CMS\Core\Database\RelationHandler::isPurged ( )

Whether item array has been purged in this instance.


Definition at line 194 of file RelationHandler.php.

◆ processDeletePlaceholder()

bool TYPO3\CMS\Core\Database\RelationHandler::processDeletePlaceholder ( )

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

‪bool Whether items have been purged

Definition at line 1251 of file RelationHandler.php.

References TYPO3\CMS\Core\Database\RelationHandler\purgeItemArrayHandler().

◆ purgeDeletePlaceholder()

array TYPO3\CMS\Core\Database\RelationHandler::purgeDeletePlaceholder (   $tableName,
array  $ids 

◆ purgeItemArray()

bool TYPO3\CMS\Core\Database\RelationHandler::purgeItemArray (   $workspaceId = null)
‪: 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.
int | null$workspaceId
‪bool Whether items have been purged

Definition at line 1225 of file RelationHandler.php.

References TYPO3\CMS\Core\Database\RelationHandler\purgeItemArrayHandler().

Referenced by TYPO3\CMS\Core\Database\RelationHandler\start().

◆ purgeItemArrayHandler()

bool TYPO3\CMS\Core\Database\RelationHandler::purgeItemArrayHandler (   $purgeCallback)

Handles a purge callback on $this->itemArray

‪bool Whether items have been purged

Definition at line 1266 of file RelationHandler.php.

References TYPO3\CMS\Core\Database\RelationHandler\removeFromItemArray().

Referenced by TYPO3\CMS\Core\Database\RelationHandler\processDeletePlaceholder(), and TYPO3\CMS\Core\Database\RelationHandler\purgeItemArray().

◆ purgeLiveVersionedIds()

array TYPO3\CMS\Core\Database\RelationHandler::purgeLiveVersionedIds (   $tableName,
array  $ids 

◆ purgeVersionedIds()

array TYPO3\CMS\Core\Database\RelationHandler::purgeVersionedIds (   $tableName,
array  $ids 

◆ readForeignField()

TYPO3\CMS\Core\Database\RelationHandler::readForeignField (   $uid,

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.

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

Definition at line 779 of file RelationHandler.php.

References $GLOBALS, TYPO3\CMS\Webhooks\Message\$uid, TYPO3\CMS\Core\Database\Connection\createQueryBuilder(), TYPO3\CMS\Core\DataHandling\PlainDataResolver\get(), TYPO3\CMS\Core\Database\RelationHandler\getConnectionForTableName(), TYPO3\CMS\Core\Database\RelationHandler\getLiveDefaultId(), TYPO3\CMS\Core\Database\RelationHandler\getResolver(), TYPO3\CMS\Core\Database\Connection\PARAM_INT, and TYPO3\CMS\Core\Database\Query\QueryHelper\parseOrderBy().

Referenced by TYPO3\CMS\Core\Database\RelationHandler\start().

◆ readList()

TYPO3\CMS\Core\Database\RelationHandler::readList (   $itemlist,
array  $configuration 

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

string$itemlist‪Item list
array$configuration‪Parent field configuration

Definition at line 314 of file RelationHandler.php.

References TYPO3\CMS\Core\Utility\MathUtility\canBeInterpretedAsInteger(), TYPO3\CMS\Core\DataHandling\PlainDataResolver\get(), TYPO3\CMS\Core\Database\RelationHandler\getLiveDefaultId(), and TYPO3\CMS\Core\Database\RelationHandler\getResolver().

Referenced by TYPO3\CMS\Core\Database\RelationHandler\start().

◆ readMM()

TYPO3\CMS\Core\Database\RelationHandler::readMM (   $tableName,

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

‪: 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.
string$tableName‪MM Tablename
int | string$uid‪Local UID
string$mmOppositeTable‪Opposite table name

Definition at line 452 of file RelationHandler.php.

References TYPO3\CMS\Webhooks\Message\$uid, TYPO3\CMS\Core\Database\Connection\createQueryBuilder(), TYPO3\CMS\Core\Database\RelationHandler\getConnectionForTableName(), TYPO3\CMS\Core\Database\Connection\PARAM_INT, TYPO3\CMS\Core\Database\Query\QueryHelper\quoteDatabaseIdentifiers(), and TYPO3\CMS\Core\Database\Query\QueryHelper\stripLogicalOperatorPrefix().

Referenced by TYPO3\CMS\Core\Database\RelationHandler\start().

◆ removeFromItemArray()

TYPO3\CMS\Core\Database\RelationHandler::removeFromItemArray (   $tableName,

◆ sanitizeIds()

TYPO3\CMS\Core\Database\RelationHandler::sanitizeIds ( array  $ids)

◆ setReferenceIndexUpdater()

TYPO3\CMS\Core\Database\RelationHandler::setReferenceIndexUpdater ( ReferenceIndexUpdater  $updater)

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

Used internally within DataHandler only

Definition at line 184 of file RelationHandler.php.

◆ setUseLiveParentIds()

TYPO3\CMS\Core\Database\RelationHandler::setUseLiveParentIds (   $useLiveParentIds)

Definition at line 295 of file RelationHandler.php.

◆ setUseLiveReferenceIds()

TYPO3\CMS\Core\Database\RelationHandler::setUseLiveReferenceIds (   $useLiveReferenceIds)

Definition at line 303 of file RelationHandler.php.

◆ setWorkspaceId()

TYPO3\CMS\Core\Database\RelationHandler::setWorkspaceId (   $workspaceId)

Sets the current workspace id.


Definition at line 174 of file RelationHandler.php.

References TYPO3\CMS\Core\Database\RelationHandler\workspaceId.

◆ sortList()

TYPO3\CMS\Core\Database\RelationHandler::sortList (   $sortby)

Does a sorting on $this->itemArray depending on a default sortby field. 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!

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

Definition at line 395 of file RelationHandler.php.

References TYPO3\CMS\Core\Database\RelationHandler\getConnectionForTableName(), TYPO3\CMS\Core\Database\Platform\PlatformInformation\getMaxBindParameters(), and TYPO3\CMS\Core\Database\Query\QueryHelper\parseOrderBy().

Referenced by TYPO3\CMS\Core\Database\RelationHandler\start().

◆ start()

TYPO3\CMS\Core\Database\RelationHandler::start (   $itemlist,
  $MMtable = '',
  $MMuid = 0,
  $currentTable = '',
  $conf = [] 

Initialization of the class.

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

Definition at line 209 of file RelationHandler.php.

References $GLOBALS, TYPO3\CMS\Core\Database\RelationHandler\purgeItemArray(), TYPO3\CMS\Core\Database\RelationHandler\readForeignField(), TYPO3\CMS\Core\Database\RelationHandler\readList(), TYPO3\CMS\Core\Database\RelationHandler\readMM(), and TYPO3\CMS\Core\Database\RelationHandler\sortList().

◆ updateRefIndex()

array TYPO3\CMS\Core\Database\RelationHandler::updateRefIndex (   $table,

Update Reference Index (sys_refindex) for a record. 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.

string$table‪Table name
int$uid‪Record uid
‪array Empty array

Definition at line 1153 of file RelationHandler.php.

References TYPO3\CMS\Webhooks\Message\$uid.

Referenced by TYPO3\CMS\Core\Database\RelationHandler\writeForeignField(), and TYPO3\CMS\Core\Database\RelationHandler\writeMM().

◆ writeForeignField()

TYPO3\CMS\Core\Database\RelationHandler::writeForeignField (   $conf,
  $updateToUid = 0 

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

array$conf‪TCA configuration for current field
int$parentUid‪The uid of the parent record
int$updateToUid‪If this is larger than zero it will be used as foreign UID instead of the given $parentUid (on Copy)

Definition at line 915 of file RelationHandler.php.

References $fields, $GLOBALS, TYPO3\CMS\Webhooks\Message\$uid, TYPO3\CMS\Core\Utility\MathUtility\canBeInterpretedAsInteger(), TYPO3\CMS\Core\Database\RelationHandler\getConnectionForTableName(), TYPO3\CMS\Core\Database\RelationHandler\getLiveDefaultId(), TYPO3\CMS\Core\Database\RelationHandler\isOnSymmetricSide(), TYPO3\CMS\Core\Database\Query\QueryHelper\parseOrderBy(), TYPO3\CMS\Core\Database\Connection\update(), and TYPO3\CMS\Core\Database\RelationHandler\updateRefIndex().

◆ writeMM()

TYPO3\CMS\Core\Database\RelationHandler::writeMM (   $MM_tableName,
  $prependTableName = false 

Writes the internal itemArray to MM table:

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

Definition at line 539 of file RelationHandler.php.

References TYPO3\CMS\Webhooks\Message\$uid, TYPO3\CMS\Core\Database\RelationHandler\completeOppositeUsageValues(), TYPO3\CMS\Core\Database\RelationHandler\getConnectionForTableName(), TYPO3\CMS\Core\Database\Connection\PARAM_INT, TYPO3\CMS\Core\Database\Query\QueryHelper\stripLogicalOperatorPrefix(), and TYPO3\CMS\Core\Database\RelationHandler\updateRefIndex().

Member Data Documentation

◆ $registerNonTableValues

bool TYPO3\CMS\Core\Database\RelationHandler::$registerNonTableValues = false

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

Definition at line 41 of file RelationHandler.php.

◆ $tableArray

array TYPO3\CMS\Core\Database\RelationHandler::$tableArray = array( )

Contains the table names as keys. The values are the id-values for each table. Should ONLY contain proper table names.

Definition at line 48 of file RelationHandler.php.

◆ workspaceId [1/2]

array<int, $itemArray = array( ); public array $nonTableArray = array( ); public array $additionalWhere = array( ); public bool $checkIfDeleted = true; protected string $firstTable = ''; protected bool $MM_is_foreign = false; protected string $MM_isMultiTableRelationship = ''; protected string $currentTable; public bool $undeleteRecord; protected array $MM_match_fields = []; protected bool $multiple = false; protected string $MM_table_where = ''; protected array $MM_oppositeUsage; protected ReferenceIndexUpdater|null $referenceIndexUpdater; protected bool $useLiveParentIds = true; protected bool $useLiveReferenceIds = true; protected int|null $workspaceId; protected bool $purged = false; public array $results = array( ); protected function getWorkspaceId(): int { $backendUser = $GLOBALS['BE_USER'] ?? null; if (!isset($this->workspaceId)) { $this-> TYPO3\CMS\Core\Database\RelationHandler::workspaceId = $backendUser instanceof BackendUserAuthentication ? (int)($backendUser->workspace) : 0

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

array<string, mixed>>

Definition at line 164 of file RelationHandler.php.

Referenced by TYPO3\CMS\Core\Database\RelationHandler\setWorkspaceId().

◆ workspaceId [2/2]

return $this TYPO3\CMS\Core\Database\RelationHandler::workspaceId

Definition at line 166 of file RelationHandler.php.