[FEATURE] #102745 - PSR-14 Events for modifying ContentObject stdWrap…

… functionality (TYPO3-Documentation#3922)

Resolves: TYPO3-Documentation/Changelog-To-Doc#793
Releases: main

Documentation/ApiOverview/Events/Events/Frontend/AfterStdWrapFunctionsExecutedEvent.rst

@@ -0,0 +1,39 @@
+..  include:: /Includes.rst.txt
+..  index:: Events; AfterStdWrapFunctionsExecutedEvent
+..  _AfterStdWrapFunctionsExecutedEvent:
+
+==================================
+AfterStdWrapFunctionsExecutedEvent
+==================================
+
+..  versionadded:: 13.0
+    This event is one of the more powerful replacements for the removed hook
+    :php:`$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['tslib/class.tslib_content.php']['stdWrap']`.
+
+The PSR-14 event
+:php:`\TYPO3\CMS\Frontend\ContentObject\Event\AfterStdWrapFunctionsExecutedEvent`
+is called after the content has been modified by the rest of the
+:ref:`stdWrap <t3tsref:stdwrap>` functions.
+
+Calling order of similar events:
+
+*   :ref:`BeforeStdWrapFunctionsInitializedEvent`
+*   :ref:`AfterStdWrapFunctionsInitializedEvent`
+*   :ref:`BeforeStdWrapFunctionsExecutedEvent`
+*   AfterStdWrapFunctionsExecutedEvent
+
+..  seealso::
+    :ref:`EnhanceStdWrapEvent`
+
+
+Example
+=======
+
+Have a look into the
+:ref:`example of EnhanceStdWrapEvent <EnhanceStdWrapEvent-example>`.
+
+
+API
+===
+
+..  include:: /CodeSnippets/Events/Frontend/AfterStdWrapFunctionsExecutedEvent.rst.txt

Documentation/ApiOverview/Events/Events/Frontend/AfterStdWrapFunctionsInitializedEvent.rst

@@ -0,0 +1,39 @@
+..  include:: /Includes.rst.txt
+..  index:: Events; AfterStdWrapFunctionsInitializedEvent
+..  _AfterStdWrapFunctionsInitializedEvent:
+
+=====================================
+AfterStdWrapFunctionsInitializedEvent
+=====================================
+
+..  versionadded:: 13.0
+    This event is one of the more powerful replacements for the removed hook
+    :php:`$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['tslib/class.tslib_content.php']['stdWrap']`.
+
+The PSR-14 event
+:php:`\TYPO3\CMS\Frontend\ContentObject\Event\AfterStdWrapFunctionsInitializedEvent`
+is dispatched after any :ref:`stdWrap <t3tsref:stdwrap>` functions have been
+initialized, but before any content gets modified or replaced.
+
+Calling order of similar events:
+
+*   :ref:`BeforeStdWrapFunctionsInitializedEvent`
+*   AfterStdWrapFunctionsInitializedEvent
+*   :ref:`BeforeStdWrapFunctionsExecutedEvent`
+*   :ref:`AfterStdWrapFunctionsExecutedEvent`
+
+..  seealso::
+    :ref:`EnhanceStdWrapEvent`
+
+
+Example
+=======
+
+Have a look into the
+:ref:`example of EnhanceStdWrapEvent <EnhanceStdWrapEvent-example>`.
+
+
+API
+===
+
+..  include:: /CodeSnippets/Events/Frontend/AfterStdWrapFunctionsInitializedEvent.rst.txt

Documentation/ApiOverview/Events/Events/Frontend/BeforeStdWrapFunctionsExecutedEvent.rst

@@ -0,0 +1,39 @@
+..  include:: /Includes.rst.txt
+..  index:: Events; BeforeStdWrapFunctionsExecutedEvent
+..  _BeforeStdWrapFunctionsExecutedEvent:
+
+===================================
+BeforeStdWrapFunctionsExecutedEvent
+===================================
+
+..  versionadded:: 13.0
+    This event is one of the more powerful replacements for the removed hook
+    :php:`$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['tslib/class.tslib_content.php']['stdWrap']`.
+
+The PSR-14 event
+:php:`\TYPO3\CMS\Frontend\ContentObject\Event\BeforeStdWrapFunctionsExecutedEvent`
+is called directly after the recursive :ref:`stdWrap <t3tsref:stdwrap>` function
+call, but still before the content gets modified.
+
+Calling order of similar events:
+
+*   :ref:`BeforeStdWrapFunctionsInitializedEvent`
+*   :ref:`AfterStdWrapFunctionsInitializedEvent`
+*   BeforeStdWrapFunctionsExecutedEvent
+*   :ref:`AfterStdWrapFunctionsExecutedEvent`
+
+..  seealso::
+    :ref:`EnhanceStdWrapEvent`
+
+
+Example
+=======
+
+Have a look into the
+:ref:`example of EnhanceStdWrapEvent <EnhanceStdWrapEvent-example>`.
+
+
+API
+===
+
+..  include:: /CodeSnippets/Events/Frontend/BeforeStdWrapFunctionsExecutedEvent.rst.txt

Documentation/ApiOverview/Events/Events/Frontend/BeforeStdWrapFunctionsInitializedEvent.rst

@@ -0,0 +1,38 @@
+..  include:: /Includes.rst.txt
+..  index:: Events; BeforeStdWrapFunctionsInitializedEvent
+..  _BeforeStdWrapFunctionsInitializedEvent:
+
+======================================
+BeforeStdWrapFunctionsInitializedEvent
+======================================
+
+..  versionadded:: 13.0
+    This event is one of the more powerful replacements for the removed hook
+    :php:`$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['tslib/class.tslib_content.php']['stdWrap']`.
+
+The PSR-14 event
+:php:`\TYPO3\CMS\Frontend\ContentObject\Event\BeforeStdWrapFunctionsInitializedEvent`
+is dispatched before any :ref:`stdWrap <t3tsref:stdwrap>` function is initialized/called.
+
+Calling order of similar events:
+
+*   BeforeStdWrapFunctionsInitializedEvent
+*   :ref:`AfterStdWrapFunctionsInitializedEvent`
+*   :ref:`BeforeStdWrapFunctionsExecutedEvent`
+*   :ref:`AfterStdWrapFunctionsExecutedEvent`
+
+..  seealso::
+    :ref:`EnhanceStdWrapEvent`
+
+
+Example
+=======
+
+Have a look into the
+:ref:`example of EnhanceStdWrapEvent <EnhanceStdWrapEvent-example>`.
+
+
+API
+===
+
+..  include:: /CodeSnippets/Events/Frontend/BeforeStdWrapFunctionsInitializedEvent.rst.txt

Documentation/ApiOverview/Events/Events/Frontend/EnhanceStdWrapEvent.rst

@@ -0,0 +1,45 @@
+..  include:: /Includes.rst.txt
+..  index:: Events; EnhanceStdWrapEvent
+..  _EnhanceStdWrapEvent:
+
+===================
+EnhanceStdWrapEvent
+===================
+
+..  versionadded:: 13.0
+    This event is one of the more powerful replacements for the removed hook
+    :php:`$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['tslib/class.tslib_content.php']['stdWrap']`.
+
+Listeners to the PSR-14 event
+:php:`\TYPO3\CMS\Frontend\ContentObject\Event\EnhanceStdWrapEvent` are able to
+modify the :ref:`stdWrap <t3tsref:stdwrap>` processing, enhancing the
+functionality and manipulating the final result/content. This is the parent
+event, which allows the corresponding listeners to be called on each step.
+
+Child events:
+
+*   :ref:`BeforeStdWrapFunctionsInitializedEvent`
+*   :ref:`AfterStdWrapFunctionsInitializedEvent`
+*   :ref:`BeforeStdWrapFunctionsExecutedEvent`
+*   :ref:`AfterStdWrapFunctionsExecutedEvent`
+
+All events provide the same functionality. The difference is only the execution
+order in which they are called in the :typoscript:`stdWrap` processing chain.
+
+
+..  _EnhanceStdWrapEvent-example:
+
+Example
+=======
+
+..  literalinclude:: _EnhanceStdWrapEvent/_MyEventListener.php
+    :language: php
+    :caption: EXT:my_extension/Classes/Frontend/EventListener/MyEventListener.php
+
+..  include:: /_includes/EventsAttributeAddedNew.rst.txt
+
+
+API
+===
+
+..  include:: /CodeSnippets/Events/Frontend/EnhanceStdWrapEvent.rst.txt

Documentation/ApiOverview/Events/Events/Frontend/_EnhanceStdWrapEvent/_MyEventListener.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MyVendor\MyExtension\Frontend\EventListener;
+
+use TYPO3\CMS\Core\Attribute\AsEventListener;
+use TYPO3\CMS\Frontend\ContentObject\Event\AfterStdWrapFunctionsExecutedEvent;
+use TYPO3\CMS\Frontend\ContentObject\Event\AfterStdWrapFunctionsInitializedEvent;
+use TYPO3\CMS\Frontend\ContentObject\Event\BeforeStdWrapFunctionsInitializedEvent;
+use TYPO3\CMS\Frontend\ContentObject\Event\EnhanceStdWrapEvent;
+
+final class MyEventListener
+{
+    #[AsEventListener(
+        identifier: 'my-extension/my-stdwrap-enhancement'
+    )]
+    public function __invoke(EnhanceStdWrapEvent $event): void
+    {
+        // listen to all events
+    }
+
+    #[AsEventListener(
+        identifier: 'my-extension/my-stdwrap-before-initialized'
+    )]
+    public function individualListener(BeforeStdWrapFunctionsInitializedEvent $event): void
+    {
+        // listen on BeforeStdWrapFunctionsInitializedEvent only
+    }
+
+    #[AsEventListener(
+        identifier: 'my-extension/my-stdwrap-after-initialized-executed'
+    )]
+    public function listenOnMultipleEvents(
+        AfterStdWrapFunctionsInitializedEvent|AfterStdWrapFunctionsExecutedEvent $event
+    ): void {
+        // Union type to listen to different events
+    }
+}

Documentation/CodeSnippets/Config/Api/Events/EventsFrontend.php

@@ -105,4 +105,34 @@
         'targetFileName' => 'CodeSnippets/Events/Frontend/ModifyRecordsAfterFetchingContentEvent.rst.txt',
         'withCode' => false,
     ],
+    [
+        'action' => 'createPhpClassDocs',
+        'class' => \TYPO3\CMS\Frontend\ContentObject\Event\EnhanceStdWrapEvent::class,
+        'targetFileName' => 'CodeSnippets/Events/Frontend/EnhanceStdWrapEvent.rst.txt',
+        'withCode' => false,
+    ],
+    [
+        'action' => 'createPhpClassDocs',
+        'class' => \TYPO3\CMS\Frontend\ContentObject\Event\BeforeStdWrapFunctionsInitializedEvent::class,
+        'targetFileName' => 'CodeSnippets/Events/Frontend/BeforeStdWrapFunctionsInitializedEvent.rst.txt',
+        'withCode' => false,
+    ],
+    [
+        'action' => 'createPhpClassDocs',
+        'class' => \TYPO3\CMS\Frontend\ContentObject\Event\AfterStdWrapFunctionsInitializedEvent::class,
+        'targetFileName' => 'CodeSnippets/Events/Frontend/AfterStdWrapFunctionsInitializedEvent.rst.txt',
+        'withCode' => false,
+    ],
+    [
+        'action' => 'createPhpClassDocs',
+        'class' => \TYPO3\CMS\Frontend\ContentObject\Event\BeforeStdWrapFunctionsExecutedEvent::class,
+        'targetFileName' => 'CodeSnippets/Events/Frontend/BeforeStdWrapFunctionsExecutedEvent.rst.txt',
+        'withCode' => false,
+    ],
+    [
+        'action' => 'createPhpClassDocs',
+        'class' => \TYPO3\CMS\Frontend\ContentObject\Event\AfterStdWrapFunctionsExecutedEvent::class,
+        'targetFileName' => 'CodeSnippets/Events/Frontend/AfterStdWrapFunctionsExecutedEvent.rst.txt',
+        'withCode' => false,
+    ],
 ];

Documentation/CodeSnippets/Events/Frontend/AfterStdWrapFunctionsExecutedEvent.rst.txt

@@ -0,0 +1,22 @@
+.. Generated by https://github.com/TYPO3-Documentation/t3docs-codesnippets
+.. php:namespace::  TYPO3\CMS\Frontend\ContentObject\Event
+
+.. php:class:: AfterStdWrapFunctionsExecutedEvent
+
+   Event is called after the content has been modified by the rest of the stdWrap functions
+
+   .. php:method:: getContent()
+
+      :returntype: string
+
+   .. php:method:: setContent(string $content)
+
+      :param string $content: the content
+
+   .. php:method:: getConfiguration()
+
+      :returntype: array
+
+   .. php:method:: getContentObjectRenderer()
+
+      :returntype: TYPO3\\CMS\\Frontend\\ContentObject\\ContentObjectRenderer

Documentation/CodeSnippets/Events/Frontend/AfterStdWrapFunctionsInitializedEvent.rst.txt

@@ -0,0 +1,23 @@
+.. Generated by https://github.com/TYPO3-Documentation/t3docs-codesnippets
+.. php:namespace::  TYPO3\CMS\Frontend\ContentObject\Event
+
+.. php:class:: AfterStdWrapFunctionsInitializedEvent
+
+   Event is dispatched after stdWrap functions have been initialized,
+   but before any content gets modified or replaced.
+
+   .. php:method:: getContent()
+
+      :returntype: string
+
+   .. php:method:: setContent(string $content)
+
+      :param string $content: the content
+
+   .. php:method:: getConfiguration()
+
+      :returntype: array
+
+   .. php:method:: getContentObjectRenderer()
+
+      :returntype: TYPO3\\CMS\\Frontend\\ContentObject\\ContentObjectRenderer

Documentation/CodeSnippets/Events/Frontend/BeforeStdWrapFunctionsExecutedEvent.rst.txt

@@ -0,0 +1,22 @@
+.. Generated by https://github.com/TYPO3-Documentation/t3docs-codesnippets
+.. php:namespace::  TYPO3\CMS\Frontend\ContentObject\Event
+
+.. php:class:: BeforeStdWrapFunctionsExecutedEvent
+
+   Event is called directly after the recursive stdWrap function call but still before the content gets modified
+
+   .. php:method:: getContent()
+
+      :returntype: string
+
+   .. php:method:: setContent(string $content)
+
+      :param string $content: the content
+
+   .. php:method:: getConfiguration()
+
+      :returntype: array
+
+   .. php:method:: getContentObjectRenderer()
+
+      :returntype: TYPO3\\CMS\\Frontend\\ContentObject\\ContentObjectRenderer

Documentation/CodeSnippets/Events/Frontend/BeforeStdWrapFunctionsInitializedEvent.rst.txt

@@ -0,0 +1,22 @@
+.. Generated by https://github.com/TYPO3-Documentation/t3docs-codesnippets
+.. php:namespace::  TYPO3\CMS\Frontend\ContentObject\Event
+
+.. php:class:: BeforeStdWrapFunctionsInitializedEvent
+
+   Event is dispatched before any stdWrap function is initialized / called
+
+   .. php:method:: getContent()
+
+      :returntype: string
+
+   .. php:method:: setContent(string $content)
+
+      :param string $content: the content
+
+   .. php:method:: getConfiguration()
+
+      :returntype: array
+
+   .. php:method:: getContentObjectRenderer()
+
+      :returntype: TYPO3\\CMS\\Frontend\\ContentObject\\ContentObjectRenderer

Documentation/CodeSnippets/Events/Frontend/EnhanceStdWrapEvent.rst.txt

@@ -0,0 +1,24 @@
+.. Generated by https://github.com/TYPO3-Documentation/t3docs-codesnippets
+.. php:namespace::  TYPO3\CMS\Frontend\ContentObject\Event
+
+.. php:class:: abstract EnhanceStdWrapEvent
+
+   Listeners to this Event are able to modify the stdWrap processing, enhancing the functionality and
+   manipulating the final result / content. This is the parent Event, which allows the corresponding
+   listeners to be called on each step, see child Events:
+
+   .. php:method:: getContent()
+
+      :returntype: string
+
+   .. php:method:: setContent(string $content)
+
+      :param string $content: the content
+
+   .. php:method:: getConfiguration()
+
+      :returntype: array
+
+   .. php:method:: getContentObjectRenderer()
+
+      :returntype: TYPO3\\CMS\\Frontend\\ContentObject\\ContentObjectRenderer