Automatic page cache clearing on Extbase record changes 

How an Extbase repository write clears the cache 

Three repository operations trigger cache clearing: adding, updating and removing a record. Each INSERT, UPDATE and DELETE that goes through the Extbase persistence layer registers the affected record — its table and UID — for later clearing. At the end of the request, Extbase resolves the registered records to page UIDs and flushes the page cache for those pages.

Two details are worth knowing:

• Clearing happens at the end of the request, not the instant you call add() or update(). Several writes in one request are collected and their pages flushed together once.
• Registration is driven by records, not relations. A write that only touches a relation (MM) table — with no record of its own — does not register a record for clearing.

Which pages an Extbase record change clears 

For each changed record, Extbase clears three kinds of page:

• Every page tagged with that record. This is the primary mechanism and the reverse of cache tags. When a page renders a record, its cache entry is tagged with <table>_<uid>. When that record changes, Extbase flushes the <table>_<uid> tag, which invalidates every page carrying it. A conference shown on ten different list pages is therefore refreshed on all ten when it changes — without anyone configuring which pages those are. The storage page below is not how a list page gets cleared; the tag is.
• The record's storage page — additionally, the page whose pid the record lives on is flushed (by its pageId_<pid> tag). This has no effect if the storagePid is a sysFolder, but for a content bearing page type it makes a difference. Consider the impact before deciding where a record stores as to not invalidate page caches for pages that might not even display that record.
• Any pages named in that page's TCEMAIN.clearCacheCmd Page TSconfig. An integrator can name further page UIDs to flush whenever any record on the storage page changes. Unlike the per-record tag above, this is a coarse, page-level rule the integrator maintains by hand — useful when a page depends on the storage folder as a whole rather than on one record.

The page cache lifetime and where it comes from 

Automatic clearing flushes a page early, when its records change. Absent any change, a cached page lives until its lifetime expires. That lifetime is not a single fixed number — it is resolved from several sources, each overriding or narrowing the previous:

1. The page's Cache timeout field (Page > Behaviour > Cache timeout). If set to a non-zero value, it wins.
2. TypoScript config.cache_period. Used when the page field is not set.
3. A framework fallback when neither of the above applies. In the calculator that handles record and page lifetimes this fallback is one year; a separate 24-hour fallback applies to the content-object rendering path. Treat these as innermost fallbacks, not as "the" default.
4. Narrowed by record visibility. The lifetime is then shortened to the next starttime or endtime of the records on the page, so a page expires no later than the moment its content becomes visible or hidden.
5. Overridden by an event. Finally, a listener on ModifyCacheLifetimeForPageEvent receives the resolved value and may replace it entirely.

Because of this chain, do not rely on a hard-coded number for "how long a page is cached". If you need the real, effective value for a given page, verify it rather than infer it:

• Inspect the cache entry. With the default database cache backend, the cache_pages table stores an expires timestamp for each cached page. The remaining lifetime is expires minus the current time.
• Observe the resolved value. A listener on ModifyCacheLifetimeForPageEvent is handed the fully resolved lifetime for the page; logging it there reports exactly what the system computed, after every source above has been applied.

The enableAutomaticCacheClearing setting for Extbase 

Automatic clearing is controlled by config.tx_extbase.persistence.enableAutomaticCacheClearing, which is enabled by default:

config.tx_extbase {
    persistence {
        # On by default. Set to 0 to stop repository writes from clearing
        # the page cache automatically.
        enableAutomaticCacheClearing = 1
    }
}

The setting gates the flush, not the registration: repository writes always register their changed records, and the setting decides whether those registered pages are cleared at the end of the request.

This is a global TypoScript setting in config.tx_extbase. It applies to every repository write on the site for as long as it is set, and there is no supported way to toggle it temporarily from PHP for a single operation — unlike \TYPO3\CMS\Core\DataHandling\DataHandler , whose runtime behaviour can be adjusted per instance. Setting it to 0 therefore means every repository write across the site stops refreshing the frontend, and clearing caches becomes your own responsibility through the cache-clearing helper. Leave it at its default unless a deliberate, site-wide cache strategy replaces it.

What automatic Extbase cache clearing does not cover 

This mechanism is Extbase's own, and it only reacts to writes made through an Extbase repository. It does not cover:

• Raw database writes — records changed with a DBAL \TYPO3\CMS\Core\Database\Query\QueryBuilder query bypass the Extbase persistence layer, register nothing, and clear no cache. After such a write you must clear the affected pages yourself with the cache-clearing helper.
• Relation-only changes — as noted above, a write that only touches an MM table registers no record.
• Caches outside the pages group — automatic clearing flushes by tag within the pages cache group, calling flushByTags() on every cache registered in that group, not only the page cache itself. A custom cache is reached by this if you register it into the pages group and tag its entries with the same <table>_<uid> value — which is exactly what you want for a cache that stores rendered output, so it is invalidated together with the page cache. A custom cache left in the default all group is not in the pages group and is not touched, so you must invalidate it yourself. The two-level list cache from the optimisation section uses the pages group for precisely this reason.

\TYPO3\CMS\Core\DataHandling\DataHandler is a different case: it is not covered by this mechanism, but it clears caches on its own. A DataHandler write registers the changed record for page-cache clearing through its own routine and honours the same TCEMAIN.clearCacheCmd Page TSconfig — so records written through DataHandler do refresh the frontend, just not via the Extbase path described here.

With this, you have the full caching picture for an Extbase plugin: cached by default, non-cacheable only when you must, invalidated precisely with cache tags, and refreshed automatically when records change.