Soft references

Default soft reference parsers

The \TYPO3\CMS\Core\DataHandling\SoftReference namespace contains generic parsers for the most well-known types, which are the default for most TYPO3 installations. This is the list of the pre-registered keys:

# Soft Reference Parsers
TYPO3\CMS\Core\DataHandling\SoftReference\SubstituteSoftReferenceParser:
  tags:
    - name: softreference.parser
      parserKey: substitute

TYPO3\CMS\Core\DataHandling\SoftReference\NotifySoftReferenceParser:
  tags:
    - name: softreference.parser
      parserKey: notify

TYPO3\CMS\Core\DataHandling\SoftReference\TypolinkSoftReferenceParser:
  tags:
    - name: softreference.parser
      parserKey: typolink

TYPO3\CMS\Core\DataHandling\SoftReference\TypolinkTagSoftReferenceParser:
  tags:
    - name: softreference.parser
      parserKey: typolink_tag

TYPO3\CMS\Core\DataHandling\SoftReference\ExtensionPathSoftReferenceParser:
  tags:
    - name: softreference.parser
      parserKey: ext_fileref

TYPO3\CMS\Core\DataHandling\SoftReference\EmailSoftReferenceParser:
  tags:
    - name: softreference.parser
      parserKey: email

TYPO3\CMS\Core\DataHandling\SoftReference\UrlSoftReferenceParser:
  tags:
    - name: softreference.parser
      parserKey: url

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="https://example.org/some-cool-feature">this cool feature</a></p>
<p>Contact: email@example.org</p>

The parsers will return an instance of \TYPO3\CMS\Core\DataHandling\SoftReference\SoftReferenceParserResult containing information about the references contained in the string. This object has two properties: $content and $elements.

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

[
    [
        '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="https://example.org/some-cool-feature">',
        'subst' => [
            'type' => 'string',
            'tokenID' => '78910',
            'tokenValue' => 'https://example.org/some-cool-feature',
        ]
    ],
    [
        'matchString' => 'email@example.org',
        'subst' => [
            'type' => 'string',
            'tokenID' => '123456',
            'tokenValue' => 'test@example.com',
        ]
    ]
]

User-defined soft reference parsers

Soft Reference Parsers can also be user-defined. It is easy to set them up by registering them in your Services.(yaml|php) file. This will load them via dependency injection:

MyVendor\Extension\SoftReference\YourSoftReferenceParser:
  tags:
    - name: softreference.parser
      parserKey: your_key

Don't forget to clear the hard caches in the admin tool after modifying DI configuration.

The soft reference parser class registered there must implement \TYPO3\CMS\Core\DataHandling\SoftReference\SoftReferenceParserInterface . This interface describes the parse method, which takes 5 parameters in total as arguments: $table, $field, $uid, $content and an optional argument $structurePath. The return type must be an instance of \TYPO3\CMS\Core\DataHandling\SoftReference\SoftReferenceParserResult . This model possesses the properties $content and $elements and has appropriate getter methods for them. The structure of these properties has been already described above. This result object should be created by its own factory method SoftReferenceParserResult::create, which expects both above-mentioned arguments to be provided. If the result is empty, SoftReferenceParserResult::createWithoutMatches should be used instead. If $elements is an empty array, this method will also be used internally.

Using the soft reference parser

To get an instance of a soft reference parser, it is recommended to use the \TYPO3\CMS\Core\DataHandling\SoftReference\SoftReferenceParserFactory class. This factory class already holds all registered instances of the parsers. They can be retrieved with the getSoftReferenceParser method. You have to provide the desired key as the first and only argument.

$softReferenceParserFactory = GeneralUtility::makeInstance(SoftReferenceParserFactory::class);
$softReferenceParser = $softReferenceParserFactory->getSoftReferenceParser('your_key');