---
title: "Feature: #111263 - Flush caches without DataHandler"
manual: "TYPO3 Core Changelog"
version: "main"
permalink: "https://docs.typo3.org/permalink/changelog:feature-111263-1793181135"
source: "Changelog/15.0/Feature-111263-FlushCachesWithoutDataHandler.rst"
typo3-version: "15.0"
typo3-major: 15
type: "feature"
issue: 111263
forge: "https://forge.typo3.org/issues/111263"
tags: ["Backend", "PHP-API", "ext:core"]
rendered: "2026-11-14T17:17:53+00:00"
---

# Feature: #111263 - Flush caches without DataHandler {#feature-111263-1793181135}

See [forge#111263](https://forge.typo3.org/issues/111263)

## Description {#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
`\TYPO3\CMS\Core\DataHandling\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
    `\TYPO3\CMS\Core\DataHandling\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**

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

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](https://docs.typo3.org/permalink/changelog:breaking-111263-1793181136):

-   **`\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
    `\TYPO3\CMS\Core\Cache\Flush\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
    `\TYPO3\CMS\Core\Cache\Flush\CacheFlushResult`, for example to
    purge a reverse proxy by the flushed cache tags.

## Impact {#impact}

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