---
title: "Soft references"
manual: "TYPO3 Explained"
version: "main"
permalink: "https://docs.typo3.org/permalink/t3coreapi:soft-references@main"
source: "ApiOverview/SoftReferences/Index.rst"
rendered: "2026-09-17T14:31:42+00:00"
---

# Soft references {#soft-references-1}

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

For example, the `tt_content.bodytext` database field can contain soft
references to pages, content elements and files. The page reference looks like
this:

```html
<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`).

You can define which soft reference parsers to use in the TCA field
[softref](https://docs.typo3.org/m/typo3/reference-tca/main/en-us/ColumnsConfig/Type/Input/Index.html#tca_property_softref) which is available for
TCA column types [text](https://docs.typo3.org/m/typo3/reference-tca/main/en-us/ColumnsConfig/Type/Text/Index.html#columns-text) and
[input](https://docs.typo3.org/m/typo3/reference-tca/main/en-us/ColumnsConfig/Type/Input/Index.html#columns-input).

## Default soft reference parsers {#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:

-   **substitute**

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

-   **typolink**

    References to page ID, record or file in typolink format. The typolink
    soft reference parser can take an additional argument, which can be
    `linklist` (`typolink['linklist']`). In this case the links will be
    separated by commas.

-   **typolink_tag**

    Same as [typolink](https://docs.typo3.org/permalink/t3coreapi:soft-references-default-parsers-typolink@main), but with
    an `<a>` tag encapsulating it.

-   **ext_fileref**

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

-   **email**

    Email highlight.

-   **url**

    URL highlights (with a scheme).

The default setup is found in [EXT:core/Configuration/Services.yaml (GitHub)](https://github.com/typo3/typo3/blob/main/typo3/sysext/core/Configuration/Services.yaml):

**Excerpt from EXT:core/Configuration/Services.yaml**

```yaml
services:
  # ... other configuration

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

  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 {#examples}

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

**Excerpt from EXT:frontend/Configuration/TCA/tt_content.php**

```php
<?php

$GLOBALS['TCA']['tt_content']['columns']['bodytext'] = [
  // ...
  'config' => [
    'type' => 'text',
    'softref' => 'typolink_tag,email[subst],url',
    // ...
  ],
  // ...
];

```

This means, the parsers for the soft reference types `typolink_tag`, `email` and
`url` will all be applied. The email soft reference parser receives the
additional parameter `subst`.

The content could look like this:

```html
<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`.

### Property `$content` {#property-content}

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

This property contains the input content. Links to be substituted have been
replaced by soft reference tokens.

For example: `<p>Contact: {softref:123456}</p>`

Tokens are strings like `{softref:123456}` which are placeholders for values
extracted by a soft reference parser.

For each token there is an entry in `$elements` which has a
`subst` key defining the `tokenID` and the `tokenValue`. See
below.

### Property `$elements` {#property-elements}

**Structure of the $elements property**

```php
[
    [
        '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',
        ]
    ]
]
```

This property 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 a md5 hash of a string
        uniquely defining the position of the element.
    -   `tokenValue`: The value that the token substitutes in the text.
        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 {#user-defined-soft-reference-parsers}

Soft reference parsers can be user-defined. They are set up by
registering them in your `Services.yaml` file. This will load them
via [dependency injection](https://docs.typo3.org/permalink/t3coreapi:dependency-injection@main):

**EXT:my_extension/Configuration/Services.yaml**

```yaml
services:
  # Place here the default dependency injection configuration

  MyVendor\MyExtension\SoftReference\YourSoftReferenceParser:
    tags:
      - name: softreference.parser
        parserKey: my_softref_key

```

Read [how to configure dependency injection in extensions](https://docs.typo3.org/permalink/t3coreapi:dependency-injection-in-extensions@main).

Do not forget to clear the hard caches in **System > Maintenance**
or via the `cache:flush` [CLI](https://docs.typo3.org/permalink/t3coreapi:symfony-console-commands@main) command
after modifying the DI configuration.

The soft reference parser class registered there must implement
[EXT:core/DataHandling/SoftReference/SoftReferenceParserInterface.php (GitHub)](https://github.com/typo3/typo3/blob/main/typo3/sysext/core/DataHandling/SoftReference/SoftReferenceParserInterface.php).
This interface describes the `parse` method, which takes 5 parameters in
total as arguments:

-   `$table`
-   `$field`
-   `$uid`
-   `$content`
-   `$structurePath` (optional)

The return type must be an instance of
[EXT:core/DataHandling/SoftReference/SoftReferenceParserResult.php (GitHub)](https://github.com/typo3/typo3/blob/main/typo3/sysext/core/DataHandling/SoftReference/SoftReferenceParserResult.php).
This model possesses the properties `$content` and `$elements` and has
appropriate getter methods for them. The structure of these properties has been
described in the [examples](https://docs.typo3.org/permalink/t3coreapi:soft-references-examples@main) section. 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 {#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.

**EXT:my_extension/Classes/MyController.php**

```php
<?php

declare(strict_types=1);

use TYPO3\CMS\Core\DataHandling\SoftReference\SoftReferenceParserFactory;

final class MyController
{
  public function __construct(
    private readonly SoftReferenceParserFactory $softReferenceParserFactory,
  ) {}

  public function doSomething(): void
  {
    // Get the soft reference parser with the key "my_softref_key"
    $mySoftRefParser = $this->softReferenceParserFactory->getSoftReferenceParser(
      'my_softref_key',
    );

    // ... do something with $mySoftRefParser
  }
}

```