New in version 12.0: This event serves as a more powerful and flexible alternative for the 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, does the new Event now allow to always modify the link explanation of any type. Additionally, this also 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


class TYPO3\CMS\Backend\Form\Event\ModifyLinkExplanationEvent

Listeners to this Event will be able to modify the link explanation array, used in FormEngine for link fields

Return type:array
Return type:array
Return type:array
Return type:array
setLinkExplanation(array linkExplanation)
  • $linkExplanation (array) – the linkExplanation
getLinkExplanationValue(string key, mixed default = NULL)
  • $key (string) – the key
  • $default (mixed) – the default, default: NULL
Return type:


setLinkExplanationValue(string key, mixed value)
  • $key (string) – the key
  • $value (mixed) – the value


Registration of the Event in your extensions’ Services.yaml:

    - name: event.listener
      identifier: 'my-package/backend/modify-link-explanation'

The corresponding event listener class:

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') {
            $event->setLinkExplanationValue('icon', $this->iconFactory->getIcon('my-custom-link-icon', Icon::SIZE_SMALL)->render());