Feature: #111263 - Flush caches without DataHandler 

See forge#111263

Description 

The cache flushing logic of \TYPO3\CMS\Core\DataHandling\DataHandler has been extracted into the new service \TYPO3\CMS\Core\Cache\Flush\CacheFlusher . It flushes the caches of changed records, pages, cache tags and cache commands without a DataHandler or a backend user.

What to flush is described by a \TYPO3\CMS\Core\Cache\Flush\CacheFlushDemand :

  • CacheFlushDemand::forRecord('tt_content', 12) flushes the pages related to a record, following the Page TSconfig options TCEMAIN.clearCache_disable , TCEMAIN.clearCache_pageSiblingChildren , TCEMAIN.clearCache_pageGrandParent and TCEMAIN.clearCacheCmd , exactly like DataHandler does.
  • CacheFlushDemand::forPageTagsByPageIds(1, 2) flushes the cache tags "pageId_1" and "pageId_2" only, without resolving related pages or Page TSconfig.
  • CacheFlushDemand::forTags('news') flushes cache tags in the caches of the "pages" group. CacheFlushDemand::forTagsInGroup('system', 'news') flushes them in the caches of another group, and the group "all" flushes them in all caches, including caches without a group. withTagsInGroup() adds cache tags of a group to a demand. Cache tags of a group that does not exist are skipped.
  • CacheFlushDemand::forCommand('pages') accepts the cache commands known from TCEMAIN.clearCacheCmd .

On whose behalf caches are flushed is described by \TYPO3\CMS\Core\Cache\Flush\CacheFlushingContext : the workspace and whether flushing the "pages" group or all caches is permitted. CacheFlushingContext::fromBackendUser() derives the permissions from User TSconfig options.clearCache.pages and options.clearCache.all . The default context is unrestricted.

CacheFlusher::flush() returns a \TYPO3\CMS\Core\Cache\Flush\CacheFlushResult with the flushed cache tags per cache group, the flushed groups, the records, and what was skipped and why. CacheFlushResult::getTags() returns the cache tags of one group, or of all groups if none is given. CacheFlusher::resolve() returns the same information without flushing anything. It dispatches the two "Before" events described below as well, so their listeners must only change what is flushed and leave any follow-up work to \TYPO3\CMS\Core\Cache\Event\AfterCacheFlushedEvent .

EXT:my_extension/Classes/Service/MyImportService.php
use TYPO3\CMS\Core\Cache\Flush\CacheFlusher;
use TYPO3\CMS\Core\Cache\Flush\CacheFlushDemand;

final readonly class MyImportService
{
    public function __construct(
        private CacheFlusher $cacheFlusher,
    ) {}

    public function import(int $newsUid): void
    {
        // ... write the record ...
        $result = $this->cacheFlusher->flush(
            CacheFlushDemand::forRecord('tx_news_domain_model_news', $newsUid)
        );
    }
}
Copied!

All events are dispatched by the service itself, so callers only describe what to flush. Cache groups are flushed by dispatching the existing \TYPO3\CMS\Core\Cache\Event\CacheFlushEvent , like the cache:flush command does, so listeners of that event now also react to group flushes triggered in the backend. The "Clear cache" actions of the backend toolbar and page tree use the new service as well, and so do the cache:flushtags command and the flushing of cache tags of files, folders and file metadata by the automatic frontend cache tagging (feature toggle frontend.cache.autoTagging ). cache:flushtags --groups reports cache groups that do not exist instead of throwing an exception.

Three new PSR-14 events replace the removed hooks:

\TYPO3\CMS\Core\Cache\Event\BeforeRecordRelatedCachesAreFlushedEvent
Dispatched for every changed record with the pages, cache tags and cache commands related to it, which listeners may change with addPageId() , addTag() , hasTag() and the setters.
\TYPO3\CMS\Core\Cache\Event\BeforeCacheFlushEvent
Dispatched once per flush with the complete CacheFlushPlan , which listeners may change. Its tag methods take the cache group as an optional second argument, "pages" by default.
\TYPO3\CMS\Core\Cache\Event\AfterCacheFlushedEvent
Dispatched once after the caches were flushed, with the CacheFlushResult , for example to purge a reverse proxy by the flushed cache tags.

Impact 

Caches of records can be flushed with the same rules as in DataHandler from any place and without a backend user, and every flush reports what it flushed.