TYPO3 v15 dev-main snapshot ()

Documentation/Changelog/13.0/Feature-102835-AddPSR-14EventsToManipulateTypoLinkCodecService.rst

@@ -0,0 +1,78 @@
+.. include:: /Includes.rst.txt
+
+.. _feature-102835-1705314133:
+
+=======================================================================
+Feature: #102835 - Add PSR-14 events to manipulate TypoLinkCodecService
+=======================================================================
+
+See :issue:`102835`
+
+Description
+===========
+
+TYPO3's main API for encoding and decoding TypoLink's has been extended
+and now provides two new PSR-14 events :php:`\TYPO3\CMS\Core\LinkHandling\Event\BeforeTypoLinkEncodedEvent`
+and :php:`\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 :php:`TypoLinkCodecService`. This is no longer necessary when using the
+new events.
+
+The :php:`BeforeTypoLinkEncodedEvent` therefore allows to set :php:`$parameters`,
+to be encoded while the :php:`AfterTypoLinkDecodedEvent` allows to modify the
+decoded :php:`$typoLinkParts.`.
+
+Both events provide the used :php:`$delimiter` and the :php:`$emptyValueSymbol`
+next to the corresponding input value, either the :php:`$typoLinkParts` to be
+encoded or the :php:`$typoLink` to be decoded.
+
+Example
+=======
+
+The event listener class, using the PHP attribute :php:`#[AsEventListener]` for
+registration:
+
+..  code-block:: php
+
+    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.
+
+.. index:: PHP-API, ext:core