---
title: "Feature: #97187 - PSR-14 event for modifying link explanation"
manual: "TYPO3 Core Changelog"
version: "main"
permalink: "https://docs.typo3.org/permalink/changelog:feature-97187"
source: "Changelog/12.0/Feature-97187-PSR-14EventForModifyingLinkExplanation.rst"
typo3-version: "12.0"
typo3-major: 12
type: "feature"
issue: 97187
forge: "https://forge.typo3.org/issues/97187"
tags: ["Backend", "PHP-API", "ext:backend"]
rendered: "2026-10-01T19:27:47+00:00"
---

# Feature: #97187 - PSR-14 event for modifying link explanation {#feature-97187}

See [forge#97187](https://forge.typo3.org/issues/97187)

## Description {#description}

A new PSR-14 event `\TYPO3\CMS\Backend\Form\Event\ModifyLinkExplanationEvent`
has been introduced which serves as a more powerful and flexible alternative
for the now removed `$GLOBALS['TYPO3_CONF_VARS']['SYS']['formEngine']['linkHandler']`
hook.

While the removed hook effectively only allowed to modify the link explanation
of TCA `link` fields in case the resolved link type did not already match
one of those, implemented by TYPO3 itself, the new event now allows to
always modify the link explanation of any type. Additionally, this allows
to modify the `additionalAttributes`, displayed below the actual link
explanation field. This is especially useful for extended link handler setups.

To modify the link explanation, the following methods are available:

-   `getLinkExplanation()`: Returns the current link explanation data
-   `setLinkExplanation()`: Set the link explanation data
-   `getLinkExplanationValue()`: Returns a specific link explanation value
-   `setLinkExplanationValue()`: Sets a specific link explanation value

The link explanation array usually contains the following values:

-   `text` : The text to show in the link explanation field
-   `icon`: The markup for the icon, displayed in front of the link explanation field
-   `additionalAttributes`: The markup for additional attributes, displayed below the link explanation field

The current context can be evaluated using the following methods:

-   `getLinkData()`: Returns the resolved link data, such as the page uid
-   `getLinkParts()`: Returns the resolved link parts, such as `url`, `target` and `additionalParams`
-   `getElementData()`: Returns the full FormEngine `$data` array for the current element

## Example {#example}

Registration of the event in your extension's `Services.yaml`:

```yaml
MyVendor\MyPackage\Backend\ModifyLinkExplanationEventListener:
  tags:
    - name: event.listener
      identifier: 'my-package/backend/modify-link-explanation'
```

The corresponding event listener class:

```php
use TYPO3\CMS\Backend\Form\Event\ModifyLinkExplanationEvent;
use TYPO3\CMS\Core\Imaging\Icon;
use TYPO3\CMS\Core\Imaging\IconFactory;

final class ModifyLinkExplanationEventListener
{
    public function __construct(
        protected readonly IconFactory $iconFactory
    ) {
    }

    public function __invoke(
        ModifyLinkExplanationEvent $event
    ): void {
        // Use a custom icon for a custom link type
        if ($event->getLinkData()['type'] === 'myCustomLinkType') {
            $icon = $this->iconFactory->getIcon(
                'my-custom-link-icon',
                Icon::SIZE_SMALL
            )->render()
            $event->setLinkExplanationValue('icon', $icon);
        }
    }
}
```

## Impact {#impact}

It's now possible to fully modify the link explanation of TCA `link`
elements, using the new PSR-14 event `ModifyLinkExplanationEvent`.