Feature: #102835 - Add PSR-14 events to manipulate TypoLinkCodecService

See forge#102835

Description

TYPO3's main API for encoding and decoding TypoLink's has been extended and now provides two new PSR-14 events \TYPO3\CMS\Core\LinkHandling\Event\BeforeTypoLinkEncodedEvent and \TYPO3\CMS\Core\LinkHandling\Event\AfterTypoLinkDecodedEvent, which allow developers to fully manipulate the encoding and decoding functionality.

A common use case for extensions is to extend the TypoLink parts to allow editors adding additional information, e.g. custom attributes to be added to the link markup. Previously, this required extensions to extended / cross class TypoLinkCodecService. This is no longer necessary when using the new events.

The BeforeTypoLinkEncodedEvent therefore allows to set $parameters, to be encoded while the AfterTypoLinkDecodedEvent allows to modify the decoded $typoLinkParts..

Both events provide the used $delimiter and the $emptyValueSymbol next to the corresponding input value, either the $typoLinkParts to be encoded or the $typoLink to be decoded.

Example

The event listener class, using the PHP attribute #[AsEventListener] for registration:

use TYPO3\CMS\Core\Attribute\AsEventListener;
use TYPO3\CMS\Core\LinkHandling\Event\AfterTypoLinkDecodedEvent;
use TYPO3\CMS\Core\LinkHandling\Event\BeforeTypoLinkEncodedEvent;

final class TypoLinkCodecServiceEventListener
{
    #[AsEventListener]
    public function encodeTypoLink(BeforeTypoLinkEncodedEvent $event): void
    {
        $typoLinkParameters = $event->getParameters();

        if (str_contains($typoLinkParameters['class'] ?? '', 'foo')) {
            $typoLinkParameters['class'] .= ' bar';
            $event->setParameters($typoLinkParameters);
        }
    }

    #[AsEventListener]
    public function decodeTypoLink(AfterTypoLinkDecodedEvent $event): void
    {
        $typoLink = $event->getTypoLink();
        $typoLinkParts = $event->getTypoLinkParts();

        if (str_contains($typoLink, 'foo')) {
            $typoLinkParts['foo'] = 'bar';
            $event->setTypoLinkParts($typoLinkParts);
        }
    }
}

Impact

Using the new PSR-14 events, it's now possible to fully influence the encoding and decoding of any TypoLink.