Soft References

“Soft References” are references to database elements, files, email addresses, URLs etc. which are found inside text fields. The <link[page_id]> tag 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.

images

softref key

images

Description

HTML <img> tags for RTE images / images from upload/.

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.