[!!!][TASK] Refactor TSFE->content away (#6068)

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

Author: linawolf

Documentation/ApiOverview/Events/Events/Frontend/AfterCacheableContentIsGeneratedEvent.rst

@@ -6,6 +6,12 @@
 AfterCacheableContentIsGeneratedEvent
 =====================================
 
+..  important::
+    ..  versionchanged:: 14.0
+        Method :php:`getController()` is removed and substituted with methods :php:`getContent()`
+        and :php:`setContent()`. See also
+        `Breaking: #107578 - Event AfterCacheableContentIsGeneratedEvent changed <https://docs.typo3.org/permalink/changelog:breaking-107578-1759400756>`_´.
+
 The PSR-14 event
 :php:`\TYPO3\CMS\Frontend\Event\AfterCacheableContentIsGeneratedEvent` can be
 used to decide if a page should be stored in cache.
@@ -15,30 +21,75 @@ It can also be used to manipulate the content before it is stored in
 TYPO3's page cache. In the Core, the event is used in
 :doc:`EXT:indexed_search <ext_indexed_search:Index>` to index cacheable content.
 
-The :php:`AfterCacheableContentIsGeneratedEvent` contains the
+The :php-short:`\TYPO3\CMS\Frontend\Event\AfterCacheableContentIsGeneratedEvent` contains the
 information if a generated page is able to store in cache via the
-:php:`$event->isCachingEnabled()` method. This can be used to
-differentiate between the previous hooks `contentPostProc-cached` and
-`contentPostProc-all`. The later hook was called regardless of whether the
-cache was enabled or not.
+:php:`$event->isCachingEnabled()` method.
+
+..  _AfterCacheableContentIsGeneratedEvent-example:
 
 Example
 =======
 
-..  todo: The property TSFE->content used in the example was marked as internal
-          in v13. A substitution is needed for this.
-
-..  note::
-    Currently, the example below is outdated. It uses a - now internal -
-    property :php:`TypoScriptFrontendController->content`.
-
 ..  literalinclude:: _AfterCacheableContentIsGeneratedEvent/_MyEventListener.php
     :language: php
     :caption: EXT:my_extension/Classes/Frontend/EventListener/MyEventListener.php
 
 ..  include:: /_includes/EventsAttributeAdded.rst.txt
 
+..  _AfterCacheableContentIsGeneratedEvent-api:
+
 API
 ===
 
 ..  include:: /CodeSnippets/Events/Frontend/AfterCacheableContentIsGeneratedEvent.rst.txt
+
+..  _AfterCacheableContentIsGeneratedEvent-migration-getcontroller:
+
+Migration from `AfterCacheableContentIsGeneratedEvent::getController()`
+=======================================================================
+
+In most cases, method :php:`AfterCacheableContentIsGeneratedEvent->getController()`
+was used in event listeners to get and/or set
+:php:`TypoScriptFrontendController->content` at a late point within the frontend
+rendering chain.
+
+The event has been changed by removing :php:`getController()` and adding
+:php:`getContent()` and :php:`setContent()` instead.
+
+..  code-block:: diff
+
+     #[AsEventListener('my-extension')]
+     public function indexPageContent(AfterCacheableContentIsGeneratedEvent $event): void
+     {
+    -    $tsfe = $event->getController();
+    -    $content = $tsfe->content;
+    *    $content = $event->getContent();
+         // ... $content is manipulated here
+    -    $tsfe->content = $content;
+    *    $event->setContent($content);
+     }
+
+Extensions aiming for TYPO3 v13 and v14 compatibility in a single version can use a version
+check gate:
+
+.. code-block:: php
+
+    #[AsEventListener('my-extension')]
+    public function indexPageContent(AfterCacheableContentIsGeneratedEvent $event): void
+    {
+        if ((new Typo3Version)->getMajorVersion() < 14) {
+            // @todo: Remove if() when TYPO3 v13 compatibility is dropped, keep else body only
+            $tsfe = $event->getController();
+            $content = $tsfe->content;
+        } else {
+            $content = $event->getContent();
+        }
+        // ... $content is manipulated here
+        if ((new Typo3Version)->getMajorVersion() < 14) {
+            // @todo: Remove if() when TYPO3 v13 compatibility is dropped, keep else body only
+            $tsfe = $event->getController();
+            $tsfe->content = $content;
+        } else {
+            $event->setContent($content);
+        }
+    }

Documentation/ApiOverview/Events/Events/Frontend/AfterCachedPageIsPersistedEvent.rst

@@ -1,20 +1,17 @@
-.. include:: /Includes.rst.txt
-.. index:: Events; AfterCachedPageIsPersistedEvent
-.. _AfterCachedPageIsPersistedEvent:
+..  include:: /Includes.rst.txt
+..  index:: Events; AfterCachedPageIsPersistedEvent
+..  _AfterCachedPageIsPersistedEvent:
 
 ===============================
 AfterCachedPageIsPersistedEvent
 ===============================
 
-   This event together with :ref:`AfterCacheableContentIsGeneratedEvent` has
-   been introduced to serve as a direct replacement for the removed hook:
-
-   * :php:`$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['tslib/class.tslib_fe.php']['insertPageIncache']`
-
 The PSR-14 event :php:`\TYPO3\CMS\Frontend\Event\AfterCachedPageIsPersistedEvent`
 is commonly used to generate a static file cache. This event is only called if
 the page was actually stored in TYPO3's page cache.
 
+..  _AfterCachedPageIsPersistedEvent-example:
+
 Example
 =======
 
@@ -24,6 +21,8 @@ Example
 
 ..  include:: /_includes/EventsAttributeAdded.rst.txt
 
+..  _AfterCachedPageIsPersistedEvent-api:
+
 API
 ===
 

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

@@ -18,10 +18,10 @@ public function __invoke(AfterCacheableContentIsGeneratedEvent $event): void
         if (!$event->isCachingEnabled()) {
             return;
         }
-        $event->getController()->content = str_replace(
+        $event->setContent(str_replace(
             'foo',
             'bar',
-            $event->getController()->content,
-        );
+            $event->getContent(),
+        ));
     }
 }

Documentation/ApiOverview/Events/Events/Frontend/_AfterCacheableContentIsGeneratedEvent/_MyEventListenerCompatible.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MyVendor\MyExtension\Frontend\EventListener;
+
+use TYPO3\CMS\Core\Attribute\AsEventListener;
+use TYPO3\CMS\Core\Information\Typo3Version;
+use TYPO3\CMS\Frontend\Event\AfterCacheableContentIsGeneratedEvent;
+
+final readonly class MyEventListener
+{
+    #[AsEventListener('my-extension')]
+    public function indexPageContent(AfterCacheableContentIsGeneratedEvent $event): void
+    {
+        if ((new Typo3Version())->getMajorVersion() < 14) {
+            // @todo: Remove if() when TYPO3 v13 compatibility is dropped, keep else body only
+            $tsfe = $event->getController();
+            $content = $tsfe->content;
+        } else {
+            $content = $event->getContent();
+        }
+        // ... $content is manipulated here
+        if ((new Typo3Version())->getMajorVersion() < 14) {
+            // @todo: Remove if() when TYPO3 v13 compatibility is dropped, keep else body only
+            $tsfe = $event->getController();
+            $tsfe->content = $content;
+        } else {
+            $event->setContent($content);
+        }
+    }
+}

Documentation/CodeSnippets/Events/Form/BeforeFormIsDuplicatedEvent.rst.txt

@@ -3,10 +3,11 @@
 
 ..  php:class:: BeforeFormIsDuplicatedEvent
 
-    Listeners to this event will be able to modify a form before it is duplicated.
+    Listeners to this Event will be able to modify the form definition
+    and persistence identifier before a form is duplicated.
 
-    ..  php:attr:: form
+    ..  php:attr:: formPersistenceIdentifier
         :public:
 
-    ..  php:attr:: formPersistenceIdentifier
+    ..  php:attr:: form
         :public:

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

@@ -11,8 +11,12 @@
     ..  php:method:: getRequest()
         :returns: `\Psr\Http\Message\ServerRequestInterface`
 
-    ..  php:method:: getController()
-        :returns: `\TYPO3\CMS\Frontend\Controller\TypoScriptFrontendController`
+    ..  php:method:: getContent()
+        :returns: `string`
+
+    ..  php:method:: setContent(string $content)
+
+        :param $content: the content
 
     ..  php:method:: isCachingEnabled()
         :returns: `bool`