---
title: "Introduction"
manual: "Temporal Cache Management"
version: "main"
source: "Introduction/Index.rst"
rendered: "2026-10-07T14:40:31+00:00"
---

# Introduction {#introduction}

## The problem {#introduction-problem}

TYPO3 invalidates a page cache entry when the data behind it changes, or when somebody
flushes a cache tag.
Neither happens when time simply passes.

A page or a content element with `starttime` or `endtime` changes its visibility at a
fixed moment without any record being edited.
The cached output still holds the visibility snapshot taken when it was rendered, and it
keeps holding it until its lifetime runs out or an editor clears the cache by hand.

This is the subject of TYPO3 Forge issue
[#14277](https://forge.typo3.org/issues/14277), which is still open.

### Symptoms {#introduction-symptoms}

-   **Expiring content**

    A page with an `endtime` in the past stays in cached menus.

-   **Scheduled content**

    A page with a `starttime` that has arrived does not appear in cached menus.

-   **Content elements**

    An element with `starttime`/`endtime` does not appear or disappear in cached page
    output.

-   **Anything rendered from a cached page**

    Sitemaps, breadcrumbs and listings inherit the same stale snapshot.

## What this extension does {#introduction-solution}

The extension registers a listener on
`TYPO3\CMS\Frontend\Event\ModifyCacheLifetimeForPageEvent`.
When TYPO3 writes a page cache entry, the listener asks the configured strategies for the
next `starttime`/`endtime` transition and shortens the entry's lifetime so it ends
there.
The page is then regenerated at that moment with the correct visibility.

An alternative mode replaces the shortened lifetime with a Scheduler task that flushes the
affected cache tags in the background.
Which of the two runs is a configuration choice; see [Configuration](../Configuration/Index.html#configuration).

### Default behavior and its cost {#introduction-default-behavior}

> [!WARNING]
> Out of the box the extension uses **global scoping** with **dynamic timing**
> (`scoping.strategy = global`, `timing.strategy = dynamic`).
> In that combination the lifetime of *every* page cache entry is cut back to the
> earliest upcoming transition anywhere on the site, so **all page caches expire at every
> temporal transition**, not only the caches of the affected pages.

That is a deliberate default: it is the safest setting and needs no configuration.
It is also the most expensive one, and on a site with frequent transitions it can flatten
the cache hit ratio.

The extension ships two ways to narrow it:

-   `scoping.strategy = per-page` shortens a page's lifetime for content on that page only.
    Page transitions are still watched site-wide, because a page appearing or disappearing
    changes menus everywhere.
-   `timing.strategy = scheduler` (with `per-page` or `per-content` scoping) stops
    shortening lifetimes altogether and flushes individual `pageId_*` tags from a
    background task instead.

Read [Performance considerations](../Performance/Index.html#performance-considerations) before deploying to a site where the cache hit
ratio matters, and [What each scoping strategy does](../Architecture/Index.html#architecture-scoping) for what each strategy actually covers.

## Status {#introduction-status}

> [!IMPORTANT]
> `ext_emconf.php` declares version **1.0.2** and state **stable**.
> The API covered by [Public API](../Api/Index.html#api) follows Semantic Versioning from 1.0.0 onwards.

The approach itself is a workaround.
TYPO3's cache API has no absolute expiration timestamp, so the extension can only
approximate one by shortening relative lifetimes or by flushing tags from a scheduled task.
A solution inside TYPO3 core would not need either.
See [Approach, limits and a core solution](../Phases/Index.html#phases) for what such a solution would look like and what would change here.

## Requirements {#introduction-requirements}

| Requirement | Value |
| --- | --- |
| TYPO3 | `^12.4 \|\| ^13.4 \|\| ^14.3` |
| PHP | `^8.1` |
| Required TYPO3 extensions | `scheduler`, `reports` |
| License | GPL-2.0-or-later |

## Quick start {#introduction-quick-start}

**Install**

```bash
composer require netresearch/nr-temporal-cache
```

Run the database analyzer afterwards so the indexes from [`ext_tables.sql`](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/FileStructure/ExtTablesSql.html#file-extension-ext-tables-sql) are
created, then confirm the installation:

**Verify**

```bash
vendor/bin/typo3 temporalcache:verify
```

No configuration is required.
The extension is active as soon as it is installed, with global scoping and dynamic timing.

## Next steps {#introduction-next-steps}

-   [Installation](../Installation/Index.html#installation) — setup and verification in detail
-   [Configuration](../Configuration/Index.html#configuration) — scoping, timing and harmonization options
-   [Performance considerations](../Performance/Index.html#performance-considerations) — what the defaults cost and how to narrow them
-   [Architecture](../Architecture/Index.html#architecture) — how the listener, strategies and queries fit together