TYPO3 11.5 API: ReferenceIndex

ReferenceIndex implements LoggerAwareInterface uses LoggerAwareTrait

Reference index processing and relation extraction

Internal

Extensions shouldn't fiddle with the reference index themselves, it's task of DataHandler to do this.

Interfaces

LoggerAwareInterface

Properties

$eventDispatcher : EventDispatcherInterface
$excludedColumns : array<string|int, mixed>: Definition of fields to exclude from ReferenceIndex in *every* table
$excludedTables : array<string|int, mixed>: 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<string|int, mixed>: An index of all found references of a single record
$softReferenceParserFactory : SoftReferenceParserFactory
$tableRelationFieldCache : array<string|int, mixed>: A list of fields that may contain relations per TCA table.
$temp_flexRelations : array<string|int, mixed>: This array holds the FlexForm references of a record
$workspaceId : int: Current workspace id

Methods

__construct() : mixed
disableRuntimeCache() : mixed: Disables the runtime-based cache
enableRuntimeCache() : mixed: Enables the runtime-based caches Could lead to side effects, depending if the reference index instance is run multiple times while records would be changed.
getNumberOfReferencedRecords() : int: Returns the amount of references for the given record
getRelations() : array<string|int, mixed>: 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<string|int, mixed>: Setting the value of a reference or removing it completely.
setWorkspaceId() : mixed: Sets the current workspace id
updateIndex() : array<string|int, mixed>: Updating Index (External API)
updateRefIndexTable() : array<string|int, mixed>: 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<string|int, mixed>|bool: Create array with field/value pairs ready to insert in database
fetchTableRelationFields() : array<string|int, mixed>: Returns all fields of a table which could contain a relation
generateDataUsingRecord() : array<string|int, mixed>: Calculate the relations for a record of a given table
getAmountOfUnusedTablesInReferenceIndex() : int
getBackendUser() : BackendUserAuthentication: Returns the current BE user.
getRecord() : array<string|int, mixed>|false: Get one record from database.
getRelations_procDB() : array<string|int, mixed>|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

$eventDispatcher


    protected
        EventDispatcherInterface
    $eventDispatcher

$excludedColumns

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


    protected
        array<string|int, mixed>
    $excludedColumns
     = ['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()

$excludedTables

Definition of tables to exclude from the ReferenceIndex


    protected
        array<string|int, mixed>
    $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()

$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

$relations

An index of all found references of a single record


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

$softReferenceParserFactory


    protected
        SoftReferenceParserFactory
    $softReferenceParserFactory

$tableRelationFieldCache

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


    protected
        array<string|int, mixed>
    $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.

$temp_flexRelations

This array holds the FlexForm references of a record


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

$workspaceId

Current workspace id


    protected
        int
    $workspaceId
     = 0

__construct()


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

Parameters

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

disableRuntimeCache()

Disables the runtime-based cache


    public
                    disableRuntimeCache() : mixed

Deprecated

since v11, will be removed in v12.

enableRuntimeCache()

Enables the runtime-based caches Could lead to side effects, depending if the reference index instance is run multiple times while records would be changed.


    public
                    enableRuntimeCache() : mixed

Deprecated

since v11, will be removed in v12.

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<string|int, mixed> $row[, string $onlyField = '' ]) : array<string|int, mixed>

Parameters

$table : string: Table name
$row : array<string|int, mixed>: Row from table
$onlyField : string = '': Specific field to fetch for.

Return values

array<string|int, mixed> —

Array with information about relations

getRelations_flexFormCallBack()

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


    public
                    getRelations_flexFormCallBack(array<string|int, mixed> $dsArr, mixed $dataValue, array<string|int, mixed> $PA, string $structurePath) : mixed

Parameters

$dsArr : array<string|int, mixed>: Data structure for the current value
$dataValue : mixed: Current value
$PA : array<string|int, mixed>: Additional configuration used in calling function
$structurePath : string: Path of value in DS structure

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<string|int, mixed>

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<string|int, mixed> —

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

updateIndex()

Updating Index (External API)


    public
                    updateIndex(bool $testOnly[, ProgressListenerInterface|null $progressListener = null ]) : array<string|int, mixed>

Parameters

$testOnly : bool: If set, only a test
$progressListener : ProgressListenerInterface|null = null: If set, the current progress is added to the listener

Return values

array<string|int, mixed> —

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<string|int, mixed>

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<string|int, mixed> —

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<string|int, mixed> $record, string $fieldName, string $flexPointer, array<string|int, mixed> $items) : mixed

Parameters

$tableName : string: Tablename of source record (where reference is located)
$record : array<string|int, mixed>: 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<string|int, mixed>: Data array with database relations (table/id)

createEntryDataForSoftReferencesUsingRecord()

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


    protected
                    createEntryDataForSoftReferencesUsingRecord(string $tableName, array<string|int, mixed> $record, string $fieldName, string $flexPointer, array<string|int, mixed> $keys) : mixed

Parameters

$tableName : string: Tablename of source record (where reference is located)
$record : array<string|int, mixed>: 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<string|int, mixed>: Data array with soft reference keys

createEntryDataUsingRecord()

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


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

Parameters

$tableName : string: Tablename of source record (where reference is located)
$record : array<string|int, mixed>: 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<string|int, mixed>|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<string|int, mixed>

Parameters

$tableName : string: Name of the table

Return values

array<string|int, mixed> —

Fields which may contain relations

generateDataUsingRecord()

Calculate the relations for a record of a given table


    protected
                    generateDataUsingRecord(string $tableName, array<string|int, mixed> $record) : array<string|int, mixed>

Parameters

$tableName : string: Table being processed
$record : array<string|int, mixed>: Record from $tableName

Return values

array<string|int, mixed>

getAmountOfUnusedTablesInReferenceIndex()


    protected
                    getAmountOfUnusedTablesInReferenceIndex(array<string|int, mixed> $tableNames) : int

Parameters

$tableNames : array<string|int, mixed>

Return values

int

getBackendUser()

Returns the current BE user.


    protected
                    getBackendUser() : BackendUserAuthentication

Return values

BackendUserAuthentication

getRecord()

Get one record from database.


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

Parameters

$tableName : string
$uid : int

Return values

array<string|int, mixed>|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<string|int, mixed> $conf, int $uid[, string $table = '' ][, array<string|int, mixed> $row = [] ]) : array<string|int, mixed>|bool

Parameters

$value : string: Field value
$conf : array<string|int, mixed>: Field configuration array of type "TCA/columns
$uid : int: Field uid
$table : string = '': Table name
$row : array<string|int, mixed> = []

Return values

array<string|int, mixed>|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

Return values

int

isDbReferenceField()

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


    protected
                    isDbReferenceField(array<string|int, mixed> $configuration) : bool

Parameters

$configuration : array<string|int, mixed>: 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<string|int, mixed> $configuration) : bool

Parameters

$configuration : array<string|int, mixed>: Config array for TCA/columns field

Return values

bool —

TRUE if reference field

removeReferenceIndexDataFromUnusedDatabaseTables()


    protected
                    removeReferenceIndexDataFromUnusedDatabaseTables(array<string|int, mixed> $tableNames) : void

Parameters

$tableNames : array<string|int, mixed>

setReferenceValue_dbRels()

Setting a value for a reference for a DB field:


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

Parameters

$refRec : array<string|int, mixed>: sys_refindex record
$itemArray : array<string|int, mixed>: Array of references from that field
$newValue : string|null: Value to substitute current value with (or NULL to unset it)
$dataArray : array<string|int, mixed>: 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<string|int, mixed> $refRec, array<string|int, mixed> $softref, string $newValue, array<string|int, mixed> &$dataArray[, string $flexPointer = '' ]) : string

Parameters

$refRec : array<string|int, mixed>: sys_refindex record
$softref : array<string|int, mixed>: Array of soft reference occurrences
$newValue : string: Value to substitute current value with
$dataArray : array<string|int, mixed>: 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

ReferenceIndex implements LoggerAwareInterface uses LoggerAwareTrait

Table of Contents

Interfaces

Properties

Methods

Properties

$eventDispatcher

$excludedColumns

Tags

$excludedTables

Tags

$hashVersion

Tags

$relations

$softReferenceParserFactory

$tableRelationFieldCache

$temp_flexRelations

Tags

$workspaceId

Methods

__construct()

Parameters

disableRuntimeCache()

enableRuntimeCache()

getNumberOfReferencedRecords()

Parameters

Return values

getRelations()

Parameters

Tags

Return values

getRelations_flexFormCallBack()

Parameters

Tags

setReferenceValue()

Parameters

Return values

setWorkspaceId()

Parameters

Tags

updateIndex()

Parameters

Tags

Return values

updateRefIndexTable()

Parameters

Return values

createEntryDataForDatabaseRelationsUsingRecord()

Parameters

createEntryDataForSoftReferencesUsingRecord()

Parameters

createEntryDataUsingRecord()

Parameters

Return values

fetchTableRelationFields()

Parameters

Return values

generateDataUsingRecord()

Parameters

Return values

getAmountOfUnusedTablesInReferenceIndex()

Parameters

Return values

getBackendUser()

Return values

getRecord()

Parameters

Return values

getRelations_procDB()

Parameters

Return values

getWorkspaceId()

Tags

Return values

isDbReferenceField()

Parameters

Return values

isReferenceField()

Parameters

Return values