ReferenceIndex

class \TYPO3\CMS\Core\Database\ReferenceIndex

Implements
LoggerAwareInterface
Uses
LoggerAwareTrait

Reference index processing and relation extraction

Table of Contents

Interfaces

LoggerAwareInterface

Properties

$eventDispatcher  : EventDispatcherInterface
$excludedColumns  : array
Definition of fields to exclude from ReferenceIndex in *every* table
$excludedTables  : array
Definition of tables to exclude from the ReferenceIndex
$hashVersion  : int
Number which we can increase if a change in the code means we will have to force a re-generation of the index.
$relations  : array
An index of all found references of a single record
$softReferenceParserFactory  : SoftReferenceParserFactory
$tableRelationFieldCache  : array
A list of fields that may contain relations per TCA table.
$temp_flexRelations  : array
This array holds the FlexForm references of a record
$workspaceId  : int
Current workspace id

Methods

__construct()  : mixed
getNumberOfReferencedRecords()  : int
Returns the amount of references for the given record
getRelations()  : array
Returns relation information for a $table/$row-array Traverses all fields in input row which are configured in TCA/columns It looks for hard relations to records in the TCA types "select" and "group"
getRelations_flexFormCallBack()  : mixed
Callback function for traversing the FlexForm structure in relation to finding DB references!
setReferenceValue()  : string|bool|array
Setting the value of a reference or removing it completely.
setWorkspaceId()  : mixed
Sets the current workspace id
updateIndex()  : array
Updating Index (External API)
updateRefIndexTable()  : array
Call this function to update the sys_refindex table for a record (even one just deleted) NOTICE: Currently, references updated for a deleted-flagged record will not include those from within FlexForm fields in some cases where the data structure is defined by another record since the resolving process ignores deleted records! This will also result in bad cleaning up in DataHandler I think... Anyway, that's the story of FlexForms; as long as the DS can change, lots of references can get lost in no time.
createEntryDataForDatabaseRelationsUsingRecord()  : mixed
Add database references to ->relations array based on fetched record
createEntryDataForSoftReferencesUsingRecord()  : mixed
Add SoftReference references to ->relations array based on fetched record
createEntryDataUsingRecord()  : array|bool
Create array with field/value pairs ready to insert in database
fetchTableRelationFields()  : array
Returns all fields of a table which could contain a relation
generateDataUsingRecord()  : array
Calculate the relations for a record of a given table
getAmountOfUnusedTablesInReferenceIndex()  : int
getBackendUser()  : BackendUserAuthentication
getRecord()  : array|false
Get one record from database.
getRelations_procDB()  : array|bool
Check field configuration if it is a DB relation field and extract DB relations if any
getWorkspaceId()  : int
Gets the current workspace id
isDbReferenceField()  : bool
Returns TRUE if the TCA/columns field type is a DB reference field
isReferenceField()  : bool
Returns TRUE if the TCA/columns field type is a reference field
removeReferenceIndexDataFromUnusedDatabaseTables()  : void
setReferenceValue_dbRels()  : string
Setting a value for a reference for a DB field:
setReferenceValue_softreferences()  : string
Setting a value for a soft reference token
shouldExcludeTableColumnFromReferenceIndex()  : bool
Checks if a given column in a given table should be excluded in the ReferenceIndex process
shouldExcludeTableFromReferenceIndex()  : bool
Checks if a given table should be excluded from ReferenceIndex

Properties

$eventDispatcher

protected EventDispatcherInterface $eventDispatcher

$excludedColumns

Definition of fields to exclude from ReferenceIndex in *every* table

protected array $excludedColumns = ['uid' => true, 'perms_userid' => true, 'perms_groupid' => t…
Show the full value['uid' => true, 'perms_userid' => true, 'perms_groupid' => true, 'perms_user' => true, 'perms_group' => true, 'perms_everybody' => true, 'pid' => true]

Implemented as array with fields as keys and booleans as values for fast isset() lookup instead of slow in_array()

Tags

see
getRelations()
see
fetchTableRelationFields()
see
shouldExcludeTableColumnFromReferenceIndex()

$excludedTables

Definition of tables to exclude from the ReferenceIndex

protected array $excludedTables = ['sys_log' => true, 'tx_extensionmanager_domain_model_extension' => true]

Only tables which do not contain any relations and never did so far since references also won't be deleted for these. Since only tables with an entry in $GLOBALS['TCA] are handled by ReferenceIndex there is no need to add *_mm-tables.

Implemented as array with fields as keys and booleans as values for fast isset() lookup instead of slow in_array()

Tags

see
updateRefIndexTable()
see
shouldExcludeTableFromReferenceIndex()

$hashVersion

Number which we can increase if a change in the code means we will have to force a re-generation of the index.

protected int $hashVersion = 1

Tags

see
updateRefIndexTable()

$relations

An index of all found references of a single record

protected array $relations = []

$tableRelationFieldCache

A list of fields that may contain relations per TCA table.

protected array $tableRelationFieldCache = []

This is either ['*'] or an array of single field names. The list depends on TCA and is built when a first table row is handled.

$workspaceId

Current workspace id

protected int $workspaceId = 0

Methods

__construct()

public __construct([EventDispatcherInterface|null $eventDispatcher = null ][, SoftReferenceParserFactory|null $softReferenceParserFactory = null ]) : mixed

Parameters

$eventDispatcher : EventDispatcherInterface|null = null
$softReferenceParserFactory : SoftReferenceParserFactory|null = null

getNumberOfReferencedRecords()

Returns the amount of references for the given record

public getNumberOfReferencedRecords(string $tableName, int $uid) : int

Parameters

$tableName : string
$uid : int

Return values

int

getRelations()

Returns relation information for a $table/$row-array Traverses all fields in input row which are configured in TCA/columns It looks for hard relations to records in the TCA types "select" and "group"

public getRelations(string $table, array $row[, string $onlyField = '' ]) : array

Parameters

$table : string

Table name

$row : array

Row from table

$onlyField : string = ''

Specific field to fetch for.

Tags

see
export_addRecord()

Return values

array —

Array with information about relations

getRelations_flexFormCallBack()

Callback function for traversing the FlexForm structure in relation to finding DB references!

public getRelations_flexFormCallBack(array $dsArr, mixed $dataValue, array $PA, string $structurePath) : mixed

Parameters

$dsArr : array

Data structure for the current value

$dataValue : mixed

Current value

$PA : array

Additional configuration used in calling function

$structurePath : string

Path of value in DS structure

Tags

see
DataHandler::checkValue_flex_procInData_travDS()
see
FlexFormTools::traverseFlexFormXMLData()

setReferenceValue()

Setting the value of a reference or removing it completely.

public setReferenceValue(string $hash, mixed $newValue[, bool $returnDataArray = false ][, bool $bypassWorkspaceAdminCheck = false ]) : string|bool|array

Usage: For lowlevel clean up operations! WARNING: With this you can set values that are not allowed in the database since it will bypass all checks for validity! Hence it is targeted at clean-up operations. Please use DataHandler in the usual ways if you wish to manipulate references. Since this interface allows updates to soft reference values (which DataHandler does not directly) you may like to use it for that as an exception to the warning above. Notice; If you want to remove multiple references from the same field, you MUST start with the one having the highest sorting number. If you don't the removal of a reference with a lower number will recreate an index in which the remaining references in that field has new hash-keys due to new sorting numbers - and you will get errors for the remaining operations which cannot find the hash you feed it! To ensure proper working only admin-BE_USERS in live workspace should use this function

Parameters

$hash : string

32-byte hash string identifying the record from sys_refindex which you wish to change the value for

$newValue : mixed

Value you wish to set for reference. If NULL, the reference is removed (unless a soft-reference in which case it can only be set to a blank string). If you wish to set a database reference, use the format "[table]:[uid]". Any other case, the input value is set as-is

$returnDataArray : bool = false

Return $dataArray only, do not submit it to database.

$bypassWorkspaceAdminCheck : bool = false

If set, it will bypass check for workspace-zero and admin user

Return values

string|bool|array —

FALSE (=OK), error message string or array (if $returnDataArray is set!)

setWorkspaceId()

Sets the current workspace id

public setWorkspaceId(int $workspaceId) : mixed

Parameters

$workspaceId : int

Tags

see
updateIndex()

updateIndex()

Updating Index (External API)

public updateIndex(bool $testOnly[, ProgressListenerInterface|null $progressListener = null ]) : array

Parameters

$testOnly : bool

If set, only a test

$progressListener : ProgressListenerInterface|null = null

If set, the current progress is added to the listener

Tags

todo:

Consider moving this together with the helper methods to a dedicated class.

Return values

array —

Header and body status content

updateRefIndexTable()

Call this function to update the sys_refindex table for a record (even one just deleted) NOTICE: Currently, references updated for a deleted-flagged record will not include those from within FlexForm fields in some cases where the data structure is defined by another record since the resolving process ignores deleted records! This will also result in bad cleaning up in DataHandler I think... Anyway, that's the story of FlexForms; as long as the DS can change, lots of references can get lost in no time.

public updateRefIndexTable(string $tableName, int $uid[, bool $testOnly = false ]) : array

Parameters

$tableName : string

Table name

$uid : int

UID of record

$testOnly : bool = false

If set, nothing will be written to the index but the result value will still report statistics on what is added, deleted and kept. Can be used for mere analysis.

Return values

array —

Array with statistics about how many index records were added, deleted and not altered plus the complete reference set for the record.

createEntryDataForDatabaseRelationsUsingRecord()

Add database references to ->relations array based on fetched record

protected createEntryDataForDatabaseRelationsUsingRecord(string $tableName, array $record, string $fieldName, string $flexPointer, array $items) : mixed

Parameters

$tableName : string

Tablename of source record (where reference is located)

$record : array

Record from $tableName

$fieldName : string

Fieldname of source record (where reference is located)

$flexPointer : string

Pointer to location inside FlexForm structure where reference is located in $fieldName

$items : array

Data array with database relations (table/id)

createEntryDataForSoftReferencesUsingRecord()

Add SoftReference references to ->relations array based on fetched record

protected createEntryDataForSoftReferencesUsingRecord(string $tableName, array $record, string $fieldName, string $flexPointer, array $keys) : mixed

Parameters

$tableName : string

Tablename of source record (where reference is located)

$record : array

Record from $tableName

$fieldName : string

Fieldname of source record (where reference is located)

$flexPointer : string

Pointer to location inside FlexForm structure where reference is located in $fieldName

$keys : array

Data array with soft reference keys

createEntryDataUsingRecord()

Create array with field/value pairs ready to insert in database

protected createEntryDataUsingRecord(string $tableName, array $record, string $fieldName, string $flexPointer, string $referencedTable, int $referencedUid[, string $referenceString = '' ][, int $sort = -1 ][, string $softReferenceKey = '' ][, string $softReferenceId = '' ]) : array|bool

Parameters

$tableName : string

Tablename of source record (where reference is located)

$record : array

Record from $table

$fieldName : string

Fieldname of source record (where reference is located)

$flexPointer : string

Pointer to location inside FlexForm structure where reference is located in [$field]

$referencedTable : string

In database references the tablename the reference points to. Keyword "_STRING" indicates special usage (typ. SoftReference) in $referenceString

$referencedUid : int

In database references the UID of the record (zero $referencedTable is "_STRING")

$referenceString : string = ''

For "_STRING" references: The string.

$sort : int = -1

The sorting order of references if many (the "group" or "select" TCA types). -1 if no sorting order is specified.

$softReferenceKey : string = ''

If the reference is a soft reference, this is the soft reference parser key. Otherwise empty.

$softReferenceId : string = ''

Soft reference ID for key. Might be useful for replace operations.

Return values

array|bool —

Array to insert in DB or false if record should not be processed

fetchTableRelationFields()

Returns all fields of a table which could contain a relation

protected fetchTableRelationFields(string $tableName) : array

Parameters

$tableName : string

Name of the table

Return values

array —

Fields which may contain relations

generateDataUsingRecord()

Calculate the relations for a record of a given table

protected generateDataUsingRecord(string $tableName, array $record) : array

Parameters

$tableName : string

Table being processed

$record : array

Record from $tableName

Return values

array

getAmountOfUnusedTablesInReferenceIndex()

protected getAmountOfUnusedTablesInReferenceIndex(array $tableNames) : int

Parameters

$tableNames : array

Return values

int

getRecord()

Get one record from database.

protected getRecord(string $tableName, int $uid) : array|false

Parameters

$tableName : string
$uid : int

Return values

array|false

getRelations_procDB()

Check field configuration if it is a DB relation field and extract DB relations if any

protected getRelations_procDB(string $value, array $conf, int $uid[, string $table = '' ][, array $row = [] ]) : array|bool

Parameters

$value : string

Field value

$conf : array

Field configuration array of type "TCA/columns

$uid : int

Field uid

$table : string = ''

Table name

$row : array = []

Return values

array|bool —

If field type is OK it will return an array with the database relations. Else FALSE

getWorkspaceId()

Gets the current workspace id

protected getWorkspaceId() : int

Tags

see
updateRefIndexTable()

Return values

int

isDbReferenceField()

Returns TRUE if the TCA/columns field type is a DB reference field

protected isDbReferenceField(array $configuration) : bool

Parameters

$configuration : array

Config array for TCA/columns field

Return values

bool —

TRUE if DB reference field (group/db or select with foreign-table)

isReferenceField()

Returns TRUE if the TCA/columns field type is a reference field

protected isReferenceField(array $configuration) : bool

Parameters

$configuration : array

Config array for TCA/columns field

Return values

bool —

TRUE if reference field

removeReferenceIndexDataFromUnusedDatabaseTables()

protected removeReferenceIndexDataFromUnusedDatabaseTables(array $tableNames) : void

Parameters

$tableNames : array

setReferenceValue_dbRels()

Setting a value for a reference for a DB field:

protected setReferenceValue_dbRels(array $refRec, array $itemArray, string|null $newValue, array &$dataArray[, string $flexPointer = '' ]) : string

Parameters

$refRec : array

sys_refindex record

$itemArray : array

Array of references from that field

$newValue : string|null

Value to substitute current value with (or NULL to unset it)

$dataArray : array

Data array in which the new value is set (passed by reference)

$flexPointer : string = ''

Flexform pointer, if in a flex form field.

Return values

string —

Error message if any, otherwise FALSE = OK

setReferenceValue_softreferences()

Setting a value for a soft reference token

protected setReferenceValue_softreferences(array $refRec, array $softref, string $newValue, array &$dataArray[, string $flexPointer = '' ]) : string

Parameters

$refRec : array

sys_refindex record

$softref : array

Array of soft reference occurrences

$newValue : string

Value to substitute current value with

$dataArray : array

Data array in which the new value is set (passed by reference)

$flexPointer : string = ''

Flexform pointer, if in a flex form field.

Return values

string —

Error message if any, otherwise FALSE = OK

shouldExcludeTableColumnFromReferenceIndex()

Checks if a given column in a given table should be excluded in the ReferenceIndex process

protected shouldExcludeTableColumnFromReferenceIndex(string $tableName, string $column, string $onlyColumn) : bool

Parameters

$tableName : string

Name of the table

$column : string

Name of the column

$onlyColumn : string

Name of a specific column to fetch

Return values

bool —

true if it should be excluded

shouldExcludeTableFromReferenceIndex()

Checks if a given table should be excluded from ReferenceIndex

protected shouldExcludeTableFromReferenceIndex(string $tableName) : bool

Parameters

$tableName : string

Name of the table

Return values

bool —

true if it should be excluded

On this page