[FEATURE] Introduce CacheDataCollector API

[TYPO3IncTeam]

ℹ️ View this commit on Github
👥 Authored by Sascha Nowak [email protected]
✔️ Merged by Benjamin Franzke [email protected]

Commit message

[FEATURE] Introduce CacheDataCollector API

A new API has been introduced to collect cache tags and their
lifetime during frontend rendering. This API is used in the
core to collect cache tags from page cache and content object
cache.

The API is implemented as a new PSR-7 request attribute
frontend.cache.collector to remove the dependency from TSFE.

Every cache tag has a lifetime. The minimum lifetime is
calculated from all given cache tags. API users don't have
to deal with it individually. The default lifetime for a
cache tag is 86400 seconds (24 hours).

The current TSFE api is deprecated in favor of the new API
as the current API implementation does not allow to set a
lifetime and extension authors have to workaround it. The
TSFE api will be removed with the next major version.

The frontend employs the following strategy: A relatively
early middleware adds an empty new cacheDataCollector
instance as attribute to request. Extensions rendering
code based on database records can then add cache tags
to this attribute. The FE rendering adds the final cache
content, the middleware then compiles the final cache
entries and triggers their persistence. There is an
additional event AddCacheTagEvent the middleware listens
to. It allows adding cache tags at places where the request
is not available. This is a tribute to technical debt that
can not be avoided at the moment. That event is however
marked @internal and may vanish later.

Resolves: #102422
Releases: main
Change-Id: Ice7b3b8aba7c4df3e48d3895d6388f5641fdad63
Reviewed-on: https://review.typo3.org/c/Packages/TYPO3.CMS/+/81801
Tested-by: Torben Hansen [email protected]
Tested-by: Benjamin Franzke [email protected]
Reviewed-by: Stefan Bürk [email protected]
Reviewed-by: Benjamin Franzke [email protected]
Reviewed-by: Christian Kuhn [email protected]
Reviewed-by: Torben Hansen [email protected]
Tested-by: Stefan Bürk [email protected]
Tested-by: Guido Schmechel [email protected]
Tested-by: Christian Kuhn [email protected]
Tested-by: core-ci [email protected]
Reviewed-by: Guido Schmechel [email protected]
Reviewed-by: Benni Mack [email protected]
Tested-by: Sascha Nowak [email protected]
Reviewed-by: Sascha Nowak [email protected]

➕ Added files

13.3/Deprecation-102422-TypoScriptFrontendController-addCacheTags.rst

.. include:: /Includes.rst.txt

.. _deprecation-102422-1700563266:

============================================================================================
Deprecation: #102422 - TypoScriptFrontendController->addCacheTags() and ->getPageCacheTags()
============================================================================================

See :issue:`102422`

Description
===========

The methods :php:`\TYPO3\CMS\Frontend\Controller\TypoScriptFrontendController->addCacheTags()` and
:php:`\TYPO3\CMS\Frontend\Controller\TypoScriptFrontendController->getPageCacheTags()`
have been marked as deprecated.


Impact
======

Calling the methods
:php:`\TYPO3\CMS\Frontend\Controller\TypoScriptFrontendController->addCacheTags()`
and
:php:`\TYPO3\CMS\Frontend\Controller\TypoScriptFrontendController->getPageCacheTags()`
will trigger a PHP deprecation warning.


Affected installations
======================

TYPO3 installations calling
:php:`\TYPO3\CMS\Frontend\Controller\TypoScriptFrontendController->addCacheTags()`
or
:php:`\TYPO3\CMS\Frontend\Controller\TypoScriptFrontendController->getPageCacheTags()`.


Migration
=========

.. code-block:: php

    // Before
    $GLOBALS['TSFE']->addCacheTags([
        'tx_myextension_mytable_123',
        'tx_myextension_mytable_456'
    ]);

    // After
    use TYPO3\CMS\Core\Cache\CacheTag;

    $request->getAttribute('frontend.cache.collector')->addCacheTags(
        new CacheTag('tx_myextension_mytable_123', 3600),
        new CacheTag('tx_myextension_mytable_456', 3600)
    );

.. code-block:: php

    // Before
    $GLOBALS['TSFE']->getPageCacheTags();

    // After
    $request->getAttribute('frontend.cache.collector')->getCacheTags();

.. index:: PHP-API, FullyScanned, ext:core

13.3/Feature-102422-CacheDataCollectorApi.rst

.. include:: /Includes.rst.txt

.. _feature-109999-1700506000:

==================================================================
Feature: #102422 - Introduce CacheDataCollector Api
==================================================================

See :issue:`102422`

Description
===========

A new API has been introduced 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 new PSR-7 request attribute
:php:`'frontend.cache.collector'`, which makes this API independent from TSFE.

Every cache tag has a lifetime. The minimum lifetime is calculated
from all given cache tags. API users don't have to deal with it individually.
The default lifetime for a cache tag is 86400 seconds (24 hours).

The current TSFE API is deprecated in favor of the new API, as the
current cache tag API implementation does not allow to set lifetime and
extension authors had to work around it.

Example
-------

..  code-block:: php
    :caption: Add a single cache tag

    use TYPO3\CMS\Core\Cache\CacheTag;

    $cacheDataCollector = $request->getAttribute('frontend.cache.collector');
    $cacheDataCollector->addCacheTags(
        new CacheTag('tx_myextension_mytable')
    );

..  code-block:: php
    :caption: Add multiple cache tags with different lifetimes

    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)
    );

..  code-block:: php
    :caption: Remove a cache tag

    use TYPO3\CMS\Core\Cache\CacheTag;

    $cacheDataCollector = $request->getAttribute('frontend.cache.collector');
    $cacheDataCollector->removeCacheTags(
        new CacheTag('tx_myextension_mytable_123')
    );

..  code-block:: php
    :caption: Remove multiple cache tags

    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')
    );

..  code-block:: php
    :caption: Get minimum lifetime, calculated from all cache tags

    $cacheDataCollector = $request->getAttribute('frontend.cache.collector');
    $cacheDataCollector->getLifetime();

..  code-block:: php
    :caption: Get all cache tags

    $cacheDataCollector = $request->getAttribute('frontend.cache.collector');
    $cacheDataCollector->getCacheTags();

The following event should only be used in code that has no access to the
request attribute :php:`'frontend.cache.collector'`, it is marked :php:`@internal`
and may vanish: It designed to allow passive cache-data signaling, without
exactly knowing the current context and not having the current request at hand.
It is not meant to allow for cache tag interception or extension.

..  code-block:: php
    :caption: Add cache tag without access to the request object

    $this->eventDispatcher->dispatch(
        new AddCacheTagEvent(
            new CacheTag('tx_myextension_mytable_123', 3600)
        )
    );

.. index:: PHP-API, ext:core