[FEATURE] #102422 - Introduce CacheDataCollector API

Resolves: TYPO3-Documentation/Changelog-To-Doc#1042
Releases: main, 13.4

Documentation/ApiOverview/CachingFramework/Architecture/Index.rst

@@ -118,6 +118,8 @@ an arbitrary number of tags can be assigned to an entry and one specific tag
 can be assigned to multiple cache entries. All tags a cache entry has are given
 to the cache when the entry is stored ("set").
 
+..  seealso::
+    :ref:`Frontend cache collector <typo3-request-attribute-frontend-cache-collector>`
 
 ..  _caching-architecture-core:
 

Documentation/ApiOverview/CachingFramework/Developer/Index.rst

@@ -113,3 +113,13 @@ This setup allows you to freely inject the very same cache into any class.
     <symfony-console-commands>` `cache:flush`:
 
     .. include:: /_includes/CliCacheFlush.rst.txt
+
+
+..  _caching-developer-cache-tags:
+
+Working with cache tags
+=======================
+
+The frontend cache collector API is available as a PSR-7 request attribute to
+collect cache tags and their corresponding lifetime. Find more information in
+the chapter :ref:`typo3-request-attribute-frontend-cache-collector`.

Documentation/ApiOverview/RequestLifeCycle/RequestAttributes/FrontendCacheCollector.rst

@@ -0,0 +1,118 @@
+..  include:: /Includes.rst.txt
+
+..  index::
+    Request attribute; Frontend cache collector
+..  _typo3-request-attribute-frontend-cache-collector:
+
+========================
+Frontend cache collector
+========================
+
+..  versionadded:: 13.3
+    This request attribute is a replacement for
+    :php:`TypoScriptFrontendController->addCacheTags()` and
+    :php:`TypoScriptFrontendController->getPageCacheTags()` which has been
+    deprecated with TYPO3 v13.3.
+
+An API is available to collect cache tags and their corresponding lifetime. This
+API is used in TYPO3 to accumulate cache tags from page cache and content object
+cache.
+
+The API is implemented as a PSR-7 request attribute `frontend.cache.collector`.
+
+Every cache tag has a lifetime. The minimum lifetime is calculated
+from all given cache tags. API users do not have to deal with it individually.
+The default lifetime for a cache tag is 86400 seconds (24 hours).
+
+
+..  _typo3-request-attribute-frontend-cache-collector-example-add-single-cache-tag:
+
+Example: Add a single cache tag
+===============================
+
+..  code-block:: php
+
+    // use TYPO3\CMS\Core\Cache\CacheTag;
+
+    $cacheDataCollector = $request->getAttribute('frontend.cache.collector');
+    $cacheDataCollector->addCacheTags(
+        new CacheTag('tx_myextension_mytable'),
+    );
+
+
+..  _typo3-request-attribute-frontend-cache-collector-example-add-multiple-cache-tags:
+
+Example: Add multiple cache tags with different lifetimes
+=========================================================
+
+..  code-block:: php
+
+    // use TYPO3\CMS\Core\Cache\CacheTag;
+
+    $cacheDataCollector = $request->getAttribute('frontend.cache.collector');
+    $cacheDataCollector->addCacheTags(
+        new CacheTag('tx_myextension_mytable_123', 3600),
+        new CacheTag('tx_myextension_mytable_456', 2592000),
+    );
+
+
+..  _typo3-request-attribute-frontend-cache-collector-example-remove-single-cache-tag:
+
+Example: Remove a single cache tag
+==================================
+
+..  code-block:: php
+
+    // use TYPO3\CMS\Core\Cache\CacheTag;
+
+    $cacheDataCollector = $request->getAttribute('frontend.cache.collector');
+    $cacheDataCollector->removeCacheTags(
+        new CacheTag('tx_myextension_mytable_123'),
+    );
+
+
+..  _typo3-request-attribute-frontend-cache-collector-example-remove-multiple-cache-tags:
+
+Example: Remove multiple cache tags
+===================================
+
+..  code-block:: php
+
+    // use TYPO3\CMS\Core\Cache\CacheTag;
+
+    $cacheDataCollector = $request->getAttribute('frontend.cache.collector');
+    $cacheDataCollector->removeCacheTags(
+        new CacheTag('tx_myextension_mytable_123'),
+        new CacheTag('tx_myextension_mytable_456'),
+    );
+
+
+..  _typo3-request-attribute-frontend-cache-collector-example-get-minimum-lifetime:
+
+Example: Get minimum lifetime, calculated from all cache tags
+=============================================================
+
+..  code-block:: php
+    :caption: Get minimum lifetime, calculated from all cache tags
+
+    $cacheDataCollector = $request->getAttribute('frontend.cache.collector');
+    $cacheDataCollector->getLifetime();
+
+
+..  _typo3-request-attribute-frontend-cache-collector-example-get-all-cache-tags:
+
+Example: Get all cache tags
+===========================
+
+..  code-block:: php
+
+    $cacheDataCollector = $request->getAttribute('frontend.cache.collector');
+    $cacheDataCollector->getCacheTags();
+
+
+..  _typo3-request-attribute-frontend-cache-collector-api:
+
+API
+===
+
+..  include:: /CodeSnippets/Manual/Cache/CacheDataCollector.rst.txt

Documentation/ApiOverview/RequestLifeCycle/Typo3Request.rst

@@ -206,6 +206,7 @@ The following attributes are available in **frontend** context:
 
 *    :doc:`RequestAttributes/ApplicationType`
 *    :doc:`RequestAttributes/CurrentContentObject`
+*    :doc:`RequestAttributes/FrontendCacheCollector`
 *    :doc:`RequestAttributes/FrontendCacheInstruction`
 *    :doc:`RequestAttributes/FrontendController`
 *    :doc:`RequestAttributes/FrontendPageInformation`

Documentation/CodeSnippets/Config/Api/All.php

@@ -6,6 +6,7 @@
 return array_merge(
     include ('Events/All.php'),
     include ('BackendApi.php'),
+    include ('Cache.php'),
     include ('CountryApi.php'),
     include ('Database.php'),
     include ('Entity.php'),

Documentation/CodeSnippets/Config/Api/Cache.php

@@ -0,0 +1,10 @@
+<?php
+
+return [
+    [
+        'action' => 'createPhpClassDocs',
+        'class' => \TYPO3\CMS\Core\Cache\CacheDataCollector::class,
+        'targetFileName' => 'CodeSnippets/Manual/Cache/CacheDataCollector.rst.txt',
+        'withCode' => false,
+    ],
+];

Documentation/CodeSnippets/Manual/Cache/CacheDataCollector.rst.txt

@@ -0,0 +1,29 @@
+..  Generated by https://github.com/TYPO3-Documentation/t3docs-codesnippets
+..  php:namespace::  TYPO3\CMS\Core\Cache
+
+..  php:class:: CacheDataCollector
+
+    ..  php:method:: getCacheTags()
+        :returns: `\CacheTag[]`
+
+    ..  php:method:: addCacheTags(\TYPO3\CMS\Core\Cache\CacheTag ...$cacheTags)
+
+        :param $cacheTags: the cacheTags
+
+    ..  php:method:: removeCacheTags(\TYPO3\CMS\Core\Cache\CacheTag ...$cacheTags)
+
+        :param $cacheTags: the cacheTags
+
+    ..  php:method:: restrictMaximumLifetime(int $lifetime)
+
+        :param $lifetime: the lifetime
+
+    ..  php:method:: resolveLifetime()
+        :returns: `int`
+
+    ..  php:method:: enqueueCacheEntry(\TYPO3\CMS\Core\Cache\CacheEntry $deferredCacheItem)
+
+        :param $deferredCacheItem: the deferredCacheItem
+
+    ..  php:method:: getCacheEntries()
+        :returns: `\CacheEntry[]`