Attention

TYPO3 v10 has reached end-of-life as of April 30th 2023 and is no longer being maintained. Use the version switcher on the top left of this page to select documentation for a supported version of TYPO3.

Need more time before upgrading? You can purchase Extended Long Term Support (ELTS) for TYPO3 v10 here: TYPO3 ELTS.

Soft References¶

"Soft References" are references to database elements, files, email addresses, URLs etc. which are found inside text fields. The <a href="t3://page?[page_id]> tag for page links found in bodytext fields is an example of this.

The Soft Reference parsers are used by the system to find these references and process them accordingly in import/export actions and copy operations. Also, the soft references are used by integrity checking functions.

Default soft reference parsers¶

The TYPO3\CMS\Core\Database\SoftReferenceIndex class contains generic parsers for the most well-known types which are default for most TYPO3 installations. This is the list of the possible keys:

substitute¶

softref key

substitute

Description

A full field value targeted for manual substitution (for import /export features)

notify¶

softref key

notify

Description

Just report if a value is found, nothing more.

typolink¶

softref key

typolink

Description

References to page id or file, possibly with anchor/target, possibly comma-separated list.

typolink_tag¶

softref key

typolink_tag

Description

As typolink, with an <a> tag encapsulating it.

ext_fileref¶

softref key

ext_fileref

Description

Relative file reference, prefixed EXT:[extkey]/ - for finding extension dependencies.

email¶

softref key

email

Description

Email highlight.

url¶

softref key

url

Description

URL highlights (with a scheme).

The default set up is found in typo3/sysext/core/Configuration/DefaultConfiguration.php:

'SC_OPTIONS' => [
    'GLOBAL' => [
        'softRefParser' => [
            'substitute' => \TYPO3\CMS\Core\Database\SoftReferenceIndex::class,
            'notify' => \TYPO3\CMS\Core\Database\SoftReferenceIndex::class,
            'typolink' => \TYPO3\CMS\Core\Database\SoftReferenceIndex::class,
            'typolink_tag' => \TYPO3\CMS\Core\Database\SoftReferenceIndex::class,
            'ext_fileref' => \TYPO3\CMS\Core\Database\SoftReferenceIndex::class,
            'email' => \TYPO3\CMS\Core\Database\SoftReferenceIndex::class,
            'url' => \TYPO3\CMS\Core\Database\SoftReferenceIndex::class,
        ],
    ],
    // ...
],

User-defined Soft Reference Parsers¶

Soft References can also be user-defined. It is easy to set them up by simply adding new keys in $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['GLOBAL']['softRefParser']. Use key names based on the extension you put it in, e.g. tx_myextensionkey.

The class containing the soft reference parser must have a function named findRef. Please refer to class TYPO3\CMS\Core\Database\SoftReferenceIndex for API usage and expected return values.

Using the soft reference parser¶

To use the soft reference parser in your own extensions, use \TYPO3\CMS\Backend\Utility\BackendUtility::softRefParserObj to get the parser for a specific soft reference type. For an example, take a look at \TYPO3\CMS\Linkvalidator\LinkAnalyzer::analyzeRecord.