# Soft references¶

“Soft References” are references to database elements, files, email addresses, URLs etc. which are found inside text fields.

For example, tt_content.bodytext can contain soft references to pages, to content elements, to files etc. The page reference can look like this:

<a href="t3://page?uid=1">link to page 1</a>


In contrast to this, the field pages.shortcut contains the page id of a shortcut. This is a reference, but not a soft reference.

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. For example, when you try to delete a page, TYPO3 will warn you if there are incoming page links to this page.

All references, soft and ordinary ones, are written to the reference index (table sys_refindex).

Which soft reference parsers will be used can be defined in the TCA field softref which is available for TCA column types text and input.

## 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.

### ext_fileref¶

softref key

ext_fileref

Description

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

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,
'ext_fileref' => \TYPO3\CMS\Core\Database\SoftReferenceIndex::class,
'email' => \TYPO3\CMS\Core\Database\SoftReferenceIndex::class,
'url' => \TYPO3\CMS\Core\Database\SoftReferenceIndex::class,
],
],
// ...
],


## Examples¶

For the tt_content.bodytext field of type text from the example above, the configuration looks like this:

$GLOBALS['TCA']['tt_content']['columns']['bodytext'] => // ... 'config' => [ 'type' => 'text', 'softref' => 'typolink_tag,email[subst],url', // ... ], // ... ];  This means, the parsers for the softref types typolink_tag, email and url will all be applied. The email soft reference parser gets the additional parameter ‘subst’. The content could look like this: <p><a href="t3://page?uid=96">Congratulations</a></p> <p>To read more about <a href="http://example.org/some-cool-feature">this cool feature</a></p> <p>Contact: email@example.org</p>  The parsers will return an array containing information about the references contained in the string: [ 'content' => ' <p><a href="{softref:424242}">Congratulations</a></p> <p>To read more about <a href="{softref:78910}">this cool feature</a></p> <p>Contact: {softref:123456}</p> ', 'elements' => [ [ 'matchString' => '<a href="t3://page?uid=96">', 'error' => 'There is a glitch in the universe, page 42 not found.', 'subst' => [ 'type' => 'db', 'tokenID' => '424242', 'tokenValue' => 't3://page?uid=96', 'recordRef' => 'pages:96', ] ], [ 'matchString' => '<a href="http://example.org/some-cool-feature">', 'subst' => [ 'type' => 'string', 'tokenID' => '78910', 'tokenValue' => 'http://example.org/some-cool-feature', ] ], [ 'matchString' => 'email@example.org', 'subst' => [ 'type' => 'string', 'tokenID' => '123456', 'tokenValue' => 'test@example.com', ] ] ], ],  ### The result array¶ In most cases the result array contains two keys: content and elements. #### Key content¶ This part contains the input content. Links to be substituted have been replaced by soft reference tokens. For example: :html:’ <p>Contact: {softref:123456}</p>’ Tokens are strings like {softref:123456} which are placeholders for a values extracted by a soft reference parser. For each token there in an entry in the elements key which has a subst key defining the tokenID and the tokenValue. See below. #### Key elements¶ This part is an array of arrays, each with these keys: • matchString: The value of the match. This is only for informational purposes to show what was found. • error: An error message can be set here, like “file not found” etc. • subst: exists on a successful match and defines the token from content • tokenID: The tokenID string corresponding to the token in output content, {softref:[tokenID]}. This is typically an md5 hash of a string defining uniquely the position of the element. • tokenValue: The value that the token substitutes in the text. Basically, if this value is inserted instead of the token the content should match what was inputted originally. • type: the type of substitution. file is a relative file reference, db is a database record reference, string is a manually modified string content (email, external url, phone number) • relFileName: (for file type): Relative filename. • recordRef: (for db type): Reference to DB record on the form <table>:<uid>. ## 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.