Documentation 

The 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, which is still open.

What this extension does 

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.

Status 

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 for what such a solution would look like and what would change here.

Requirements 

Quick start 

composer require netresearch/nr-temporal-cache

Run the database analyzer afterwards so the indexes from ext_tables.sql are created, then confirm the installation:

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 

• Installation — setup and verification in detail
• Configuration — scoping, timing and harmonization options
• Performance considerations — what the defaults cost and how to narrow them
• Architecture — how the listener, strategies and queries fit together

Overview 

The extension buys correct temporal behavior by making page cache entries expire earlier than they otherwise would, or by flushing them from a background task. Both cost cache hits. How many depends entirely on which scoping and timing strategy is configured, and the default is the most expensive combination.

This chapter describes what each configuration actually does, so the cost can be measured on a specific site. It contains no benchmark figures: none have been measured for this extension, and numbers from another site would not transfer.

The model in one table 

Scoping and timing are independent, and scoping answers two different questions depending on which timing strategy reads it.

Read the table before choosing a strategy. Two combinations are commonly misread:

• per-content + dynamic narrows nothing. Its precision lives in the flush tags, which dynamic timing never reads. Configuring it without switching timing gives global behavior plus refindex code that never runs.
• per-page or per-content + scheduler flushes only the tags named above. A page transition then refreshes that page, not the menus on every other page. Only global scoping refreshes those.

hybrid timing picks per record type: timing.hybrid.pages decides the lifetime calculation and page transitions, timing.hybrid.content decides content transitions.

Where the cost sits 

Query cost with dynamic timing

Every page cache write runs two MIN() queries per monitored table — four with the default pages and tt_content, two more for every table another extension registers. Each query is a single indexed aggregate returning one integer. One request carries one workspace and one language, so the query count does not grow with the number of configured languages.

Cache hit ratio

This is the cost that matters, and it is a property of the site, not of the extension: how often transitions occur, how many pages exist, and how much traffic arrives between two transitions.

Simultaneous expiry

With global scoping every entry carries the same expiry timestamp, so they all miss at once. Behind a CDN or reverse proxy that miss propagates upstream. per-page scoping spreads the timestamps for content transitions; page transitions still land on all entries at once.

Query cost with scheduler timing

Zero during page generation. The cost moves into the scheduled task, which is heavier than the lookup it replaces: each run loads every record carrying a starttime or endtime from every monitored table into PHP — one query per table, no time restriction in SQL — and then filters the run's time window in PHP. Its cost therefore scales with the total amount of temporal content on the site, not with the number of transitions in the window. Each transition that does fall in the window costs one flushByTag() per tag the scoping strategy names.

Chapters 

Related documentation 

• Architecture — the implementation behind this behavior
• Configuration — every option in detail
• Installation — installation and index verification
• Approach, limits and a core solution — why the approach is shaped this way

Scoping strategies 

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_temporal_cache']['scoping']['strategy'] = 'global';

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_temporal_cache']['scoping']['strategy'] = 'per-page';

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_temporal_cache']['scoping'] = [
    'strategy' => 'per-content',
    'use_refindex' => true,
];

vendor/bin/typo3 referenceindex:update

Timing strategies 

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_temporal_cache']['timing']['strategy'] = 'dynamic';

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_temporal_cache']['timing']['strategy'] = 'scheduler';

* * * * * php /path/to/typo3/vendor/bin/typo3 scheduler:run

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_temporal_cache']['timing'] = [
    'strategy' => 'hybrid',
    'hybrid' => [
        'pages' => 'dynamic',
        'content' => 'scheduler',
    ],
];

Time harmonization 

Harmonization is a data change, not runtime behavior. temporalcache:harmonize (and the equivalent backend action) rewrite the stored starttime/endtime values of records, moving each to its nearest configured slot. Fewer distinct transition moments means fewer cache invalidations, whatever the scoping and timing strategy.

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_temporal_cache']['harmonization'] = [
    'enabled' => true,
    'slots' => '00:00,06:00,12:00,18:00',
    'tolerance' => 3600,
];

Slot at 12:00:00, tolerance = 300 seconds

11:56:00 → 4 minutes away  → shifted to 12:00:00
12:03:00 → 3 minutes away  → shifted to 12:00:00
11:50:00 → 10 minutes away → beyond tolerance, stays 11:50:00

Before harmonize, slots 00:00,06:00,12:00,18:00, tolerance 3600:

  Article 1: starttime 05:43  → within an hour of 06:00 → rewritten to 06:00
  Article 2: starttime 06:18  → within an hour of 06:00 → rewritten to 06:00
  Article 3: starttime 11:27  → within an hour of 12:00 → rewritten to 12:00
  Article 4: starttime 12:31  → within an hour of 12:00 → rewritten to 12:00

Four distinct transition moments become two.

Combining the three 

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_temporal_cache'] = [
    'scoping' => [
        'strategy' => 'per-content',
        'use_refindex' => true,
    ],
    'timing' => [
        'strategy' => 'scheduler',
    ],
    'harmonization' => [
        'enabled' => true,
        'slots' => '00:00,06:00,12:00,18:00',
        'tolerance' => 3600,
    ],
];

What this configuration gives, and what it costs:

• No queries during page generation, because the lifetime calculation is skipped entirely.
• Invalidation limited to the pages the refindex reports for a transitioning element.
• Up to one scheduler interval of delay before a transition takes effect.
• Menus on unaffected pages are not refreshed by a page transition, because the flush tag is that page's own — this is the price of leaving global scoping.
• A scheduler run that loads all temporal records on the site, whether or not any of them transitioned.

Requires the Scheduler task to be registered and cron to be running. If either is missing, nothing invalidates anything.

Next steps 

• Limitations — what the approach cannot do
• Decision guide — which configuration matches which site
• Configuration — every option in detail

Only a relative lifetime is available 

TYPO3's cache API accepts "keep this for N seconds", not "keep this until timestamp T". ModifyCacheLifetimeForPageEvent is the only lever the extension has over a page cache entry, and it takes a duration.

The event does supply the page id (getPageId()) and the rendering instructions, so the extension can and does scope by page — but it says nothing about which records were rendered into the entry. The extension therefore has to infer the relevant transitions from the configured scope rather than from the page's actual content.

Synchronized expiry with global scoping 

With scoping.strategy = global every page cache entry written in the same second receives the same expiry timestamp: the earliest upcoming transition anywhere on the site.

Site with 10,000 pages
  Page A has a future starttime at 10:00
  Every other page has no temporal restriction

Every page cache entry written before 10:00 expires at 10:00.
After 10:00 they all miss, and each miss regenerates a page.

Two consequences follow.

Cache hit ratio

The effective lifetime of the whole page cache becomes the gap between transitions. On a site with frequent transitions that is far shorter than the lifetime the site would otherwise use.

Simultaneous misses

Because the expiry is identical rather than staggered, misses arrive together. A CDN or reverse proxy in front of TYPO3 respects the same Cache-Control window, so the burst reaches the origin as one wave.

<IfModule mod_headers.c>
    Header set Cache-Control "public, max-age=3600, stale-while-revalidate=300"
</IfModule>

sub vcl_backend_response {
    set beresp.grace = 5m;
}

limit_req_zone $binary_remote_addr zone=one:10m rate=10r/s;
limit_req zone=one burst=20 nodelay;

Query cost on every cache write 

With dynamic timing, each page cache write runs two MIN() queries per monitored table — four with the default pages and tt_content.

SELECT MIN(`starttime`) AS min_transition
FROM `tt_content`
WHERE `starttime` > :now
  AND `deleted` = 0
  AND `hidden` = 0
  AND `pid` = :pageId
  AND (`t3ver_wsid` = 0 OR `t3ver_wsid` IS NULL)
  AND `sys_language_uid` = :language

Notes on that query:

• Records with starttime = 0 are excluded by the > :now comparison; there is no separate != 0 clause.
• The deleted/hidden column names come from the table's TCA ctrl section. Where no TCA is loaded, those clauses are simply absent.
• The workspace clause is t3ver_wsid = :workspace for any workspace other than live.

The scheduler task is not free 

scheduler timing removes the per-request queries, but its task loads every record that carries a starttime or endtime from every monitored table into PHP on each run — one query per table, with no time restriction in SQL — and then filters the run's window in PHP.

Its cost scales with the total volume of temporal content on the site, not with the number of transitions that actually occurred. On a site with a lot of scheduled content, running the task every minute repeats that load every minute.

The first run has no stored timestamp and therefore processes the range from epoch to now, which flushes for every past transition once.

Scheduler flushes are narrower than they look 

Under scheduler or hybrid timing the flush tags come from the scoping strategy:

• global flushes the pages tag — everything.
• per-page flushes pageId_<uid> for a page and pageId_<pid> for a content element.
• per-content flushes one pageId_* per refindex hit; a page record still yields only its own tag.

So with per-page or per-content scoping, a page reaching its starttime refreshes that page's own cache and nothing else. Menus on other pages keep showing the old page tree until their entries expire for another reason. Only global scoping refreshes them.

Per-content scoping does not narrow lifetimes 

PerContentScopingStrategy::getNextTransition() returns the site-wide transition, the same value global returns. Narrowing it per page would risk serving stale content that was embedded from elsewhere.

Consequence: per-content combined with dynamic timing is indistinguishable from global in its cache effect. The strategy's precision is in its flush tags and needs scheduler or hybrid timing to have any effect.

Cross-page dependencies with dynamic timing 

per-page scoping looks at content elements by pid. An element rendered onto another page through a CONTENT or RECORDS cObject is therefore invisible to that page's lifetime calculation, and the embedding page keeps its long lifetime when the element transitions.

There is no configuration that fixes this for dynamic timing. per-content scoping resolves the references, but only for flush tags.

A hybrid combination that drops transitions 

timing.hybrid.pages and timing.hybrid.content both accept dynamic and scheduler, so four combinations are configurable. One of them does not work:

The scheduler task sees only live and the default language 

TemporalCacheSchedulerTask calls findTransitionsInRange() without a workspace or language argument, so it runs with the defaults: workspace 0 and sys_language_uid = 0.

Transitions on translated records are therefore not processed by scheduler or hybrid timing. On a multi-language site, use dynamic timing — which reads workspace and language from the request context — for the languages that matter.

Only the page cache 

The listener sets the page cache lifetime. Caches written by other code — an extension's own cache, a reverse proxy configured independently, a static file cache — keep whatever lifetime that code assigns.

Granularity is one second, because transitions are Unix timestamps.

No per-page-tree switch 

The configuration is global to the installation. There is no setting to exclude a page tree, a doktype or a content type from the calculation.

The workaround is a second listener on the same event, ordered after this extension's, that overrides the lifetime for the pages it wants to exclude — see Custom cache lifetime logic.

Next steps 

• Optimization strategies — the settings that change this behavior
• Decision guide — which configuration matches which site
• Architecture — the implementation these limits come from
• Approach, limits and a core solution — what a core solution would change

Four questions that decide the configuration 

Where is the temporal content?

Only in the pages table, so only menus and the page tree are affected? Or in tt_content and other records too? per-page scoping only helps when content transitions outnumber page transitions: page transitions stay site-wide in every strategy.

Is content reused across pages?

If elements are placed on one page each, per-page scoping is accurate. If CONTENT or RECORDS cObjects pull elements onto other pages, only per-content scoping resolves those references — and only for flush tags, which means scheduler or hybrid timing.

How far apart are transitions?

With dynamic timing the effective page cache lifetime is the gap to the next transition in scope. If that gap is routinely shorter than the interval in which a page would otherwise be requested twice, the page cache is doing little work.

Is a delay acceptable?

scheduler timing trades exactness for zero per-request cost. Content appears or disappears up to one scheduler interval late.

Configurations 

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_temporal_cache'] = [
    'scoping' => ['strategy' => 'global'],
    'timing' => ['strategy' => 'dynamic'],
];

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_temporal_cache'] = [
    'scoping' => ['strategy' => 'per-page'],
    'timing' => ['strategy' => 'dynamic'],
];

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_temporal_cache'] = [
    'scoping' => ['strategy' => 'per-content', 'use_refindex' => true],
    'timing' => ['strategy' => 'scheduler'],
];

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_temporal_cache'] = [
    'scoping' => ['strategy' => 'per-content', 'use_refindex' => true],
    'timing' => [
        'strategy' => 'hybrid',
        'hybrid' => [
            'pages' => 'dynamic',
            'content' => 'scheduler',
        ],
    ],
];

When not to use the extension 

No record uses starttime or endtime

Every lookup returns null and the lifetime falls back to advanced.default_max_lifetime. The queries still run. There is nothing to gain.

Correct menus everywhere are required and the full flush is unaffordable

The two are in tension: only global scoping refreshes menus on unaffected pages, and only the narrower strategies keep the cache. No configuration resolves that; see Alternative approaches for approaches that take menus out of the page cache entirely.

Manual clearing is already reliable in practice

Then the extension only adds moving parts.

What to measure 

Before deploying, on a copy of the production data:

vendor/bin/typo3 temporalcache:analyze
vendor/bin/typo3 temporalcache:list

vendor/bin/typo3 temporalcache:verify

Then measure, with the extension installed and again without it:

• The page cache hit ratio over a period covering several transitions.
• Page generation time on a cache miss, which tells you the cost of a lookup on your data volume.
• What arrives at the origin when a transition passes, if a CDN or reverse proxy is in front.

Enable advanced.debug_logging while doing this: the listener then logs the lifetime it set, the cap it applied and both strategy names for every cache write.

Next steps 

• Optimization strategies — what each setting does
• Limitations — what none of them fixes
• Alternative approaches — solving it without this extension
• Configuration — every option in detail

The trade-off in one line each 

Uncached menus (USER_INT) 

Render the navigation outside the page cache so it is rebuilt on every request.

lib.mainMenu = USER_INT
lib.mainMenu {
    userFunc = MyVendor\MyExtension\Menu\MenuProcessor->render
}

Fits when the temporal content is only in menus. The rest of the page keeps its normal cache lifetime and nothing has to expire early, which is the opposite trade to this extension: a steady per-request cost instead of periodic cache loss.

Does not help with temporal content in the page body, and a page containing a USER_INT cannot be delivered from a reverse proxy as a whole.

SSI and ESI 

Keep the page cached and let the web server or CDN assemble an uncached fragment into it at delivery time.

<div class="navigation">
    <esi:include src="/menu-fragment" />
</div>

sub vcl_recv {
    if (req.url ~ "^/menu-fragment") {
        return (pass);
    }
}

<IfModule mod_include.c>
    Options +Includes
    AddOutputFilter INCLUDES .html
</IfModule>

Fits a site that already runs Varnish or a CDN with ESI support. It is the only approach here that keeps both the page fully cached at the edge and the fragment exact.

The cost is operational: another moving part in the delivery chain, and debugging that spans TYPO3 and the proxy.

Client-side loading 

Ship the page without the time-sensitive fragment and fetch it after load.

const response = await fetch('/api/menu');
const items = await response.json();

const list = document.querySelector('.navigation ul');
list.replaceChildren(...items.map(item => {
    const link = document.createElement('a');
    link.href = item.url;
    link.textContent = item.title;

    const entry = document.createElement('li');
    entry.append(link);

    return entry;
}));

Fits an application-style frontend that is already doing this for other data.

For navigation it is usually the wrong choice: search engines and assistive technology need the links in the delivered HTML, and a fragment that appears after load is a layout shift. If it is used, the server-rendered fallback has to be correct on its own.

Scheduled cache clearing 

0 * * * * /path/to/typo3/vendor/bin/typo3 cache:flush

Fits a site with a fixed editorial rhythm — everything publishes at 09:00, 12:00 and 17:00 — where clearing shortly after those times is enough.

It does not solve the underlying problem: between two runs the output is stale, and every run discards the whole cache whether or not a transition happened. Compared to this extension with global scoping, it is the same full flush on a fixed schedule instead of on an actual transition.

Combining harmonization with the extension gets a similar grouping effect without discarding caches that nothing invalidated; see Time harmonization.

Manual clearing 

The editor clears the cache after the scheduled moment has passed.

This is the status quo the extension exists to replace. It is listed for completeness: it works, it costs nothing to set up, and it fails the first time somebody is on holiday.

Choosing between them 

Where is the temporal content?

Only in menus → an uncached menu or ESI keeps the page cache intact. In the page body → this extension, or client-side loading for that fragment.

What is in front of TYPO3?

A CDN or Varnish with ESI support makes ESI the strongest option. Without one, ESI is not available and an uncached menu costs origin CPU on every request.

How exact does it have to be?

Exact to the second → this extension with dynamic timing, an uncached menu, or ESI. Within a few minutes → this extension with scheduler timing, or scheduled clearing.

Are the approaches mutually exclusive?

No. An uncached menu plus this extension for content elements is a reasonable split: the menu never goes stale, and the extension only has to watch tt_content.

Next steps 

• Decision guide — choosing a configuration for this extension
• Optimization strategies — the settings that change its cost
• Limitations — what it cannot do
• Installation — installing it

Why does my entire site cache expire when one page has a future starttime? 

Because the default scoping strategy is global. Its transition lookup covers every monitored table site-wide and ignores the page id, so every page cache entry written in that second gets the same shortened lifetime.

Switching to per-page narrows it — but only for content elements:

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_temporal_cache']['scoping']['strategy'] = 'per-page';

A transition in the pages table still shortens every page's lifetime, in every strategy, because a page entering or leaving the tree changes menus everywhere.

Can I disable this for specific page trees? 

Not through configuration. The settings are global to the installation; there is no page-tree, doktype or content-type filter.

The workaround is a second listener on the same event, ordered after this extension's, that overrides the lifetime for the pages it should not apply to:

namespace MyVendor\MyExtension\EventListener;

use TYPO3\CMS\Frontend\Event\ModifyCacheLifetimeForPageEvent;

final class ConditionalTemporalCache
{
    /**
     * @param int[] $excludedPageIds pages that keep the long lifetime
     */
    public function __construct(private readonly array $excludedPageIds = [])
    {
    }

    public function __invoke(ModifyCacheLifetimeForPageEvent $event): void
    {
        if (\in_array($event->getPageId(), $this->excludedPageIds, true)) {
            $event->setCacheLifetime(86400);
        }
    }
}

services:
  MyVendor\MyExtension\EventListener\ConditionalTemporalCache:
    tags:
      - name: event.listener
        identifier: 'my-extension/conditional-temporal-cache'
        event: TYPO3\CMS\Frontend\Event\ModifyCacheLifetimeForPageEvent
        after: 'temporal-cache/modify-cache-lifetime'

Will this work with a CDN or Varnish? 

Yes, with one caveat. A CDN honors the Cache-Control window it is given, so a shortened page cache lifetime propagates to the edge. With global scoping every entry carries the same expiry, so the edge misses arrive together and reach the origin as one wave.

The mitigations are the usual ones — serve stale while revalidating, rate-limit the origin, warm the cache ahead of a known transition — plus the extension-side option of moving to scheduler timing, which stops shortening lifetimes altogether. See Synchronized expiry with global scoping.

Does this affect backend performance? 

The cache lifetime listener runs on frontend page cache writes only, so ordinary backend editing is untouched.

Three parts of the extension do run in the backend, on demand: the backend module, the Reports module status provider, and the console commands. The backend module and the harmonization analysis load temporal records to build their figures, so they get slower as the amount of temporal content grows.

What if I do not use temporal content at all? 

Every lookup returns null and the lifetime falls back to advanced.default_max_lifetime (default 86400), so behavior is unchanged. The queries still run on every page cache write with dynamic timing.

There is no benefit in that case — uninstall it.

How do I see what the extension is doing? 

Turn on advanced.debug_logging. The listener then logs, for every page cache write it modifies: the lifetime it set, the uncapped value, the cap and where the cap came from, and the names of both active strategies.

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_temporal_cache']['advanced']['debug_logging'] = true;

The same flag makes SchedulerTimingStrategy log each flush with the tags it flushed, and makes the scheduler task log its run window.

To see the data rather than the decisions:

vendor/bin/typo3 temporalcache:analyze   # counts and statistics
vendor/bin/typo3 temporalcache:list      # every temporal record and its next transition
vendor/bin/typo3 temporalcache:verify    # indexes and configuration

Can I combine this with cache warming? 

Yes, and it is worth doing with global scoping, where all entries expire at the same known moment. temporalcache:list reports the next transition per record, so a warming run can be scheduled shortly after it.

The extension ships no warming itself and integrates with no particular warming extension; anything that requests pages after the transition works.

What happens under load when the cache expires? 

With global scoping, every page cache entry expires at the same second, so every subsequent request is a miss until the entries are rebuilt. Under load that arrives at the origin as a single burst.

Four levers, in rough order of effectiveness:

• scheduler timing — nothing expires by time.
• per-page scoping — content transitions stagger; page transitions do not.
• Stale-while-revalidate at the edge, so the burst is absorbed.
• Cache warming timed to the known transition.

How does this work with workspaces? 

With dynamic timing, correctly and without configuration. The strategies read the workspace id from the Context API and pass it into every query; a live request and a workspace preview therefore resolve different transitions and get different lifetimes.

Can I combine this with my own cache tags? 

Yes. The extension sets the page cache lifetime and, under scheduler timing, flushes pages or pageId_* tags. It does not interfere with tags your own code adds or flushes.

If your listener also sets a lifetime, order it after temporal-cache/modify-cache-lifetime and combine the two values with min() rather than overwriting.

What does harmonization cost? 

Nothing at runtime — it changes no code path. temporalcache:harmonize rewrites the stored starttime/endtime values once, and from then on the same transition lookups simply find fewer distinct moments.

The real cost is editorial: publication times move to the nearest slot within the configured tolerance. Preview with --dry-run before running it, because the command writes by default.

Does the query cost multiply with the number of languages? 

No. One frontend request carries one language, and the language id from the Context API goes into the query as a single sys_language_uid condition. A ten-language site runs the same number of queries per cache write as a single-language site — each language just maintains its own cache entries and its own transitions.

The number of queries grows with the number of monitored tables, at two per table.

Next steps 

• Optimization strategies — what each setting changes
• Limitations — what none of them fixes
• Decision guide — choosing a configuration
• Architecture — the implementation behind the answers

Requirements 

Minimum, as declared in composer.json:

• PHP 8.1 or newer
• TYPO3 ^12.4 || ^13.0 || ^14.0
• typo3/cms-scheduler and typo3/cms-reports, both pulled in as dependencies

Database

• Four indexes are added through ext_tables.sql, two on pages and two on tt_content; run the database compare after installing
• No tables and no columns are added — the extension reads the standard starttime and endtime fields

Compatibility 

The combinations below are the ones the CI matrix in .github/workflows/ci.yml builds.

Installation methods 

composer require netresearch/nr-temporal-cache
vendor/bin/typo3 extension:setup
vendor/bin/typo3 cache:flush

Configuration 

services:
  # Register custom news table
  my_ext_news_table_registration:
    class: 'Closure'
    factory: ['@Netresearch\TemporalCache\Service\TemporalMonitorRegistry', 'registerTable']
    arguments:
      - 'tx_news_domain_model_news'
      - ['uid', 'pid', 'title', 'starttime', 'endtime', 'hidden', 'deleted', 'sys_language_uid']

  # Register custom event table
  my_ext_events_table_registration:
    class: 'Closure'
    factory: ['@Netresearch\TemporalCache\Service\TemporalMonitorRegistry', 'registerTable']
    arguments:
      - 'tx_events_domain_model_event'
      - ['uid', 'pid', 'title', 'starttime', 'endtime', 'hidden', 'deleted', 'sys_language_uid']

<?php
use Netresearch\TemporalCache\Service\TemporalMonitorRegistry;
use TYPO3\CMS\Core\Utility\GeneralUtility;

// Only use makeInstance() in ext_localconf.php where DI is not yet available
$registry = GeneralUtility::makeInstance(TemporalMonitorRegistry::class);
$registry->registerTable('tx_news_domain_model_news', [
    'uid', 'pid', 'title', 'starttime', 'endtime', 'hidden', 'deleted', 'sys_language_uid'
]);

<?php

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_temporal_cache']['advanced']['default_max_lifetime'] = 43200;

Verification 

vendor/bin/typo3 temporalcache:verify

advanced.debug_logging = 1

Troubleshooting 

SHOW INDEX FROM pages WHERE Key_name LIKE 'idx_temporalcache%';
SHOW INDEX FROM tt_content WHERE Key_name LIKE 'idx_temporalcache%';

vendor/bin/typo3 extension:setup

<?php

$GLOBALS['TYPO3_CONF_VARS']['LOG']['Netresearch']['TemporalCache']['writerConfiguration'] = [
    \TYPO3\CMS\Core\Log\LogLevel::DEBUG => [
        \TYPO3\CMS\Core\Log\Writer\FileWriter::class => [
            'logFile' => 'typo3temp/var/log/temporal_cache.log',
        ],
    ],
];

Uninstallation 

The extension adds no tables and no columns. It does add four indexes to pages and tt_content (idx_temporalcache_starttime and idx_temporalcache_endtime, see ext_tables.sql); remove them in Admin Tools → Maintenance → Analyze Database Structure after uninstalling if you do not want to keep them.

composer remove netresearch/nr-temporal-cache
vendor/bin/typo3 cache:flush

TYPO3 then reverts to its default behaviour: temporal content becomes visible when the page cache happens to expire.

Next steps 

• Configuration - Every setting and its default
• Architecture - How the listener, strategies and repository fit together
• GitHub issues - Report problems

Chapters 

All settings at a glance 

Defaults as implemented in NetresearchTemporalCacheConfigurationExtensionConfiguration.

Where to configure 

1. Admin Tools → Extensions
2. Find "nr_temporal_cache"
3. Click the "Configure" icon
4. Adjust the settings, grouped by scoping, timing, harmonization, advanced
5. Save

<?php

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_temporal_cache'] = [
    'scoping' => [
        'strategy' => 'per-page',
        'use_refindex' => true,
    ],
    'timing' => [
        'strategy' => 'dynamic',
    ],
    'harmonization' => [
        'enabled' => true,
        'slots' => '00:00,06:00,12:00,18:00',
        'tolerance' => 3600,
    ],
];

Next steps 

• Optimization strategies - Every setting in detail
• Examples & presets - Complete configurations
• Performance considerations - Performance implications
• Configuration wizard - The wizard in the backend module

How the settings combine 

The scoping strategy answers two questions, and the timing strategy decides which of the two answers is ever used:

Cache lifetime

ScopingStrategyInterface::getNextTransition() returns the next transition timestamp. The event listener caps the page cache lifetime at that timestamp. Only the dynamic timing strategy — and hybrid when its page rule is dynamic — asks for it.

Cache tags

ScopingStrategyInterface::getCacheTagsToFlush() returns the tags a transition flushes. Only the scheduler task calls TimingStrategyInterface::processTransition(), so these tags take effect with the scheduler and hybrid timing strategies. DynamicTimingStrategy::processTransition() is empty.

A scoping strategy whose benefit lies in its tags therefore has no effect while timing.strategy = dynamic.

Scoping strategy 

Controls which caches are invalidated when temporal transitions occur.

Timing strategy 

Controls when the extension checks for temporal transitions.

Time harmonization 

Rounds transition timestamps to fixed time slots so that several transitions share one cache flush.

Next steps 

• Advanced options - Cache lifetime cap, debug logging, scheduler task
• Examples & presets - Complete configuration examples
• Optimization strategies - Which combination suits which site

Advanced settings 

Scheduler task 

The scheduler and hybrid timing strategies do not flush caches themselves. They rely on NetresearchTemporalCacheTaskTemporalCacheSchedulerTask, which finds the transitions that occurred since its last run and hands each one to the active timing strategy.

ext_localconf.php registers the task type in $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['scheduler']['tasks'], the list the Scheduler module builds its task selection from, so Scheduler → Create new task offers Temporal Cache: Process transitions.

Creating the task is not enough on its own either — the Scheduler needs a cron entry that runs it:

* * * * * /usr/bin/php /var/www/html/vendor/bin/typo3 scheduler:run

scheduler:run executes every task that is due.

Verifying the setup 

vendor/bin/typo3 temporalcache:verify runs four checks:

1. An index whose leading column is starttime, and one whose leading column is endtime, on both pages and tt_content
2. scoping.strategy is one of global, per-page, per-content and timing.strategy is one of dynamic, scheduler, hybrid
3. The time slot configuration, when harmonization is enabled
4. The columns the queries rely on: starttime, endtime, hidden, deleted, sys_language_uid on both tables, plus pid on tt_content

It exits with 0 when every check passes and 1 otherwise. Add --verbose for the per-field table of the schema check.

Next steps 

• Optimization strategies - Scoping, timing and harmonization settings
• Examples & presets - Complete configuration examples
• Troubleshooting - Diagnose configuration issues

Presets offered by the wizard 

The Wizard tab of the backend module offers these three presets. The values below are the ones it shows; the wizard does not write them — apply them in the Extension Manager or in config/system/additional.php.

scoping.strategy = global
timing.strategy = dynamic
harmonization.enabled = 0

scoping.strategy = per-page
timing.strategy = hybrid
harmonization.enabled = 1
harmonization.slots = 00:00,06:00,12:00,18:00

scoping.strategy = per-content
scoping.use_refindex = 1
timing.strategy = scheduler
harmonization.enabled = 1
harmonization.slots = 00:00,04:00,08:00,12:00,16:00,20:00

Worked configurations 

scoping.strategy = per-page
timing.strategy = dynamic
harmonization.enabled = 0

scoping.strategy = per-content
scoping.use_refindex = 1
timing.strategy = hybrid
timing.hybrid.pages = dynamic
timing.hybrid.content = scheduler

harmonization.enabled = 1
harmonization.slots = 00:00,06:00,12:00,18:00
harmonization.tolerance = 3600

harmonization.enabled = 1
harmonization.slots = 09:00
harmonization.tolerance = 3600

PHP configuration 

<?php

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_temporal_cache'] = [
    'scoping' => [
        'strategy' => 'per-content',
        'use_refindex' => true,
    ],
    'timing' => [
        'strategy' => 'scheduler',
    ],
    'harmonization' => [
        'enabled' => true,
        'slots' => '00:00,06:00,12:00,18:00',
        'tolerance' => 3600,
        'auto_round' => false,
    ],
    'advanced' => [
        'default_max_lifetime' => 86400,
        'debug_logging' => false,
    ],
];

<?php

if (getenv('TYPO3_CONTEXT') === 'Development') {
    $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_temporal_cache']['advanced']['debug_logging'] = true;
}

Next steps 

• Optimization strategies - What each setting does
• Advanced options - Cache lifetime cap, debug logging, scheduler task
• Troubleshooting - Diagnose configuration issues

Start here 

vendor/bin/typo3 temporalcache:verify

The command checks the indexes and columns the queries need, the two strategy names, and the time slots when harmonization is enabled. It reports which check failed and exits with 1. See Verifying the setup for the full list of checks.

Cache not updating 

Symptoms

• Temporal content does not appear or disappear at the scheduled time
• Menus show pages whose starttime has not been reached

Checks

1. Which timing strategy is active?

   vendor/bin/typo3 temporalcache:analyze

   Copied!

   Only dynamic expires the cache by itself. scheduler relies entirely on the scheduler task, and hybrid does for whichever content type is routed to it, so check that the task exists in the Scheduler module and that cron is running it. See Scheduler task.

2. Do the indexes exist?

   The extension ships them in ext_tables.sql; TYPO3 creates them during the database compare, not at installation time.

   SHOW INDEX FROM pages WHERE Key_name LIKE 'idx_temporalcache%';
   SHOW INDEX FROM tt_content WHERE Key_name LIKE 'idx_temporalcache%';

   Copied!

   Expected on both tables: idx_temporalcache_starttime over (starttime, sys_language_uid) and idx_temporalcache_endtime over (endtime, sys_language_uid). If they are missing, run the database compare rather than creating them by hand:

   vendor/bin/typo3 extension:setup

   Copied!

   Admin Tools → Maintenance → Analyze Database Structure does the same from the backend.

3. Is the record actually visible?

   The transition queries skip records that are deleted or hidden, and they filter on the language of the current context. A hidden record's starttime never triggers anything.

4. Turn on debug logging.

   advanced.debug_logging = 1

   Copied!

   grep TemporalCache var/log/typo3_*.log | tail -50

   Copied!

   With dynamic timing, one entry per page cache generation shows the lifetime that was written and which maximum capped it.

High database load 

Symptoms

• Slow page generation with timing.strategy = dynamic
• Many MIN(starttime) / MIN(endtime) queries in the slow query log

What the extension queries

The dynamic strategy runs two MIN() queries per monitored table — one for starttime, one for endtime — on every page cache generation. With the two default tables that is four queries. Each table registered through TemporalMonitorRegistry adds two more.

The site-wide lookup used by global and per-content scoping is cached for the duration of the request; the two lookups of per-page scoping are not.

Options

1. Make sure the indexes above exist — without them these are full table scans.
2. Set timing.strategy = scheduler to remove the queries from page generation entirely. This needs the scheduler task; read Scheduler task first.

3. Check the query plan:

   EXPLAIN SELECT MIN(starttime) FROM pages
   WHERE starttime > UNIX_TIMESTAMP()
     AND hidden = 0 AND deleted = 0
     AND sys_language_uid = 0;

   Copied!

   The plan should use one of the idx_temporalcache_* indexes instead of scanning the table.

Changing scoping.strategy does not reduce this load: under dynamic timing every scoping strategy performs the same kind of lookup, and per-content performs the site-wide one.

Harmonization not working 

Symptoms

• The Content tab shows no harmonization column or no suggestions
• Timestamps stay where they were

Checks

1. harmonization.enabled = 1. While it is off, the service returns every timestamp unchanged and the backend module hides the column.
2. The slots parse. Entries must be HH:MM or H:MM with hours 0-23 and minutes 0-59; anything else is dropped silently, and with no valid slot left nothing is harmonized. temporalcache:verify reports the parsed slots when harmonization is enabled.

3. The tolerance is large enough. A timestamp is only moved when its nearest slot is at most harmonization.tolerance seconds away.

   Slots 00:00,12:00 with tolerance 3600:
   
   11:30 → nearest slot 12:00, 30 min away  → harmonized to 12:00
   10:30 → nearest slot 12:00, 90 min away  → left at 10:30

   Copied!

   harmonization.tolerance = 0 harmonizes nothing at all. The label in ext_conf_template.txt calls it "no limit", which is backwards.

4. The distance is measured within the day. 23:30 is far from a 00:00 slot, not close to the next day's.

5. Harmonization is invoked, not automatic. Nothing rewrites timestamps when an editor saves a record. Use Harmonize selected in Tools → Temporal Cache → Content, or:

   vendor/bin/typo3 temporalcache:harmonize

   Copied!

Scheduler task 

This version registers no scheduler task type, so the task cannot be created in System → Scheduler. Scheduler task describes what that means for the scheduler and hybrid timing strategies.

If a task type has been registered on your installation, verify that the Scheduler itself runs:

crontab -l | grep scheduler
vendor/bin/typo3 scheduler:run

Configuration not taking effect 

Typos in strategy names are not errors. ScopingStrategyFactory and TimingStrategyFactory activate the strategy whose name matches the configured value and fall back to the highest-priority tagged strategy — global and dynamic — when none does. A misspelled per-contnet therefore behaves exactly like the default. temporalcache:verify flags both values as INVALID.

Out-of-range values are clamped, not rejected. advanced.default_max_lifetime of 0 or less is skipped in favour of 86400.

Two configuration sources. The Extension Manager writes to config/system/settings.php; config/system/additional.php is read afterwards, so an assignment there overrides the Extension Manager value. Check both files before concluding that a setting is ignored.

Getting help 

Collect before reporting:

vendor/bin/typo3 extension:list | grep temporal_cache
vendor/bin/typo3 temporalcache:verify
vendor/bin/typo3 temporalcache:analyze
grep TemporalCache var/log/typo3_*.log | tail -50

Report at GitHub issues with the TYPO3 version, the extension version and the output above.

Next steps 

• Optimization strategies - What each setting does
• Examples & presets - Complete configuration examples
• Dashboard - What the backend module reports
• Performance considerations - Performance implications

Accessing the module 

Navigate to Tools > Temporal Cache.

Access

The module is registered for administrators only and is available in the Live workspace only. See Access and permissions.

TYPO3 versions

The extension supports TYPO3 12.4, 13 and 14 — see Installation.

The module menu offers three views. A fourth controller action, harmonize, is the endpoint the content view calls when applying harmonization; it has no view of its own.

Views 

Doc header buttons 

Every view carries a reload button and a bookmark button. The dashboard additionally offers a View Content button that opens the content view.

There is no cache-flush, export or configuration-test button in the module. Flushing caches is done through the standard TYPO3 tools:

vendor/bin/typo3 cache:flush

Command-line equivalents 

Everything the module reads is also available on the command line, and harmonization can be previewed there before it is applied:

vendor/bin/typo3 temporalcache:analyze
vendor/bin/typo3 temporalcache:list
vendor/bin/typo3 temporalcache:harmonize --dry-run
vendor/bin/typo3 temporalcache:verify

See Command-line interface for the full reference.

Related documentation 

• Configuration — configuration reference
• Command-line interface — command reference
• TYPO3 Reports module — status reporting inside the TYPO3 Reports module
• Performance considerations — performance implications
• Installation — installation and setup

Statistics cards 

Four cards across the top of the view.

Total Temporal Content

Number of pages and content elements that carry a start time or an end time, with the split into Pages and Content below the figure.

Active Content

Records that are visible at the moment the view is opened — the start time has passed or is unset, and the end time lies in the future or is unset.

Scheduled Content

Records whose start time lies in the future.

Transitions

Number of transition events in the next 30 days. A record with both a start time and an end time in that window contributes two events.

Current configuration 

Shows the active scoping strategy, the active timing strategy and whether harmonization is enabled. The values come from the extension configuration; change them under Admin Tools > Settings > Extension Configuration, see Configuration.

When harmonization is enabled and records exist whose start time would move, an additional hint appears with a View Harmonizable Content link that opens the content view with the harmonizable filter applied.

Upcoming transitions timeline 

Lists the transitions of the next seven days, grouped per day. Each day carries a badge with its number of transitions, and each entry shows:

• the time of day
• the title of the page or content element
• a Start or End badge, colored green for start and red for end
• the source record as table:uid

Days without transitions are omitted. When no transition falls into the next seven days, the card shows a note instead of the list.

Key performance indicators 

Average Transitions per Day

The number of days within the next 30 days that carry at least one transition.

Harmonization Potential

Only shown when harmonization is enabled. The number of records whose start time harmonization would move to a different slot.

Quick actions 

View All Temporal Content

Opens the content view without a filter.

Configuration Wizard

Opens the configuration wizard.

Harmonize Content

Only shown when harmonization is enabled and candidates exist. Opens the content view with the harmonizable filter applied.

The doc header additionally offers a reload button, a bookmark button, and a View Content button.

Next steps 

• Content — inspect and harmonize individual records
• Configuration wizard — review the available strategy combinations
• Command-line interface — the same data on the command line
• Performance considerations — what the strategies cost

Filters 

Seven filter buttons above the table. The active filter is kept while paging.

All Content

Every record with a start time or an end time.

Pages Only

Records from the pages table.

Content Elements

Records from the tt_content table.

Active

Records that are visible right now.

Scheduled

Records whose start time lies in the future.

Expired

Records whose end time lies in the past.

Harmonizable

Records whose start time or end time harmonization would move to a different slot.

Table columns 

Type

Page or Content, depending on the source table.

UID

The record UID. UIDs are unique per table, not across tables.

Title

Page title or content element header, with a hidden badge when the record is hidden.

Start Time, End Time

Formatted as DD.MM.YYYY HH:MM, or - when the field is not set.

Status

Active when the record is visible now, Scheduled when its start time lies in the future, Expired otherwise.

Harmonization Suggestion

Only shown when harmonization is enabled. For the start time and the end time separately: the slot harmonization would move the value to, and the shift in minutes. Records without a suggestion show -.

Rows with a harmonization suggestion are highlighted. The list is not sortable and has no search field; use temporalcache:list on the command line for sorting, filtering and export.

Pagination 

The list shows 50 records per page. Page links appear below the table as soon as there is more than one page.

Harmonizing records 

The selection column, the suggestion column and the Harmonize Selected button appear only when harmonization is enabled in the extension configuration. A checkbox is rendered only for records that actually have a suggestion.

1. Select one or more records, or use the checkbox in the table header to select all of them. Ctrl + A (Cmd + A on macOS) has the same effect while the focus is outside an input field.
2. Harmonize Selected becomes active as soon as one record is selected.
3. Confirm the dialog.
4. The selected start and end times are written to the database, the page cache group is flushed, and the view reloads.

Next steps 

• Dashboard — counts and the transition timeline
• Configuration wizard — review the available strategy combinations
• Time harmonization — configure time slots and tolerance
• Command-line interface — the same list with sorting, filtering and export

Wizard steps 

The wizard is a single backend action that renders one step at a time, selected by a step parameter in the URL. Opening Configuration Wizard from the module menu starts at the welcome step.

Presets in detail 

The preset definitions live in the module controller. Enter the values shown here in the extension configuration to reproduce a preset.

'scoping' => ['strategy' => 'global'],
'timing' => ['strategy' => 'dynamic'],
'harmonization' => ['enabled' => false],

'scoping' => ['strategy' => 'per-page'],
'timing' => ['strategy' => 'hybrid'],
'harmonization' => ['enabled' => true, 'slots' => '00:00,06:00,12:00,18:00'],

'scoping' => ['strategy' => 'per-content', 'use_refindex' => true],
'timing' => ['strategy' => 'scheduler'],
'harmonization' => ['enabled' => true, 'slots' => '00:00,04:00,08:00,12:00,16:00,20:00'],

Next steps 

• Configuration — where the settings are actually entered
• Optimization strategies — what the scoping and timing strategies do
• Dashboard — check the effect after changing the configuration
• Tips and best practices — practical recommendations

Check the database indexes first 

The extension ships the indexes it needs in ext_tables.sql: an index led by starttime and one led by endtime, on pages and on tt_content. They are created by the schema migrator, not by the extension itself.

vendor/bin/typo3 extension:setup

vendor/bin/typo3 temporalcache:verify

The same check appears in the Reports module. Without these indexes every temporal lookup falls back to a full table scan.

Using harmonization effectively 

Align the slots with your editorial rhythm

If articles are published at 09:00, 13:00 and 17:00, use exactly those times as slots. Timestamps are only moved when they lie within the configured tolerance of a slot, so slots far from your actual publishing times harmonize nothing.

Review the shifts before applying them

The Harmonization Suggestion column in the content view shows the shift in minutes per record. A large shift moves content visibility noticeably; decide per record whether that is acceptable.

Preview a bulk run on the command line

temporalcache:harmonize --dry-run lists every pending change without writing. Run it before harmonizing from the backend, since the backend writes bypass the DataHandler and leave no history entry to revert.

Start small

Harmonize one table at a time with --table=pages or --table=tt_content.

Managing temporal content 

Clean up expired records

The Expired filter lists everything past its end time.

Watch for clustering

The dashboard timeline shows how many transitions fall on the same day. Many transitions on one day mean many cache invalidations on that day; that is where harmonization pays off.

Export an inventory

The backend list has no export. Use temporalcache:list with --format=csv or --format=json.

Troubleshooting 

Access and permissions 

The module is registered for administrators only ('access' => 'admin') and is available in the Live workspace only ('workspaces' => 'live'). Non-administrators do not see it in the Tools section.

To hide it from an administrator as well, use TSconfig:

options.hideModules := addToList(tools_TemporalCache)

Before applying harmonization the module additionally checks write access to every monitored table — by default pages and tt_content, plus any table registered through TemporalMonitorRegistry. Administrators pass this check unconditionally. When the check fails, the request is rejected with a message naming the tables the user cannot modify.

Next steps 

• Configuration — complete configuration reference
• Command-line interface — command reference
• Performance considerations — performance impact analysis
• Dashboard — monitor your temporal cache

Command overview 

Only temporalcache:harmonize is registered as schedulable (schedulable: true in Configuration/Services.yaml). The other three commands are not offered in the scheduler.

Options shared with every Symfony command 

Besides the options documented per command, the standard Symfony console options apply. Two of them change the output of these commands:

-v, --verbose

Adds extra output sections. What each command adds is documented in its own section below.

-n, --no-interaction

Answers interactive questions with their default. temporalcache:harmonize is the only command that asks one, and its default answer is no — so a non-interactive run of that command writes nothing.

temporalcache:analyze 

Reads temporal content and reports statistics, upcoming transitions and — when harmonization is enabled — the reduction harmonization would achieve. The command never writes to the database and always exits with code 0.

vendor/bin/typo3 temporalcache:analyze

vendor/bin/typo3 temporalcache:analyze --workspace=1 --days=60 --verbose

vendor/bin/typo3 temporalcache:analyze --language=-1

temporalcache:verify 

Checks that the database and the extension configuration are in the state the extension needs. The command takes no options of its own and writes nothing.

Exit code 0 means every check passed, exit code 1 means at least one check failed. That makes the command usable as a health probe in monitoring or deployment pipelines.

vendor/bin/typo3 temporalcache:verify

vendor/bin/typo3 temporalcache:verify --verbose

if vendor/bin/typo3 temporalcache:verify >/dev/null 2>&1; then
    echo "Temporal cache system healthy"
else
    echo "Temporal cache system reported issues"
fi

temporalcache:list 

Lists pages and content elements that carry a start time or an end time. The command writes nothing. It exits with 1 when --table, --sort or --format receives a value outside its allowed set, and with 0 otherwise — including when the result set is empty.

vendor/bin/typo3 temporalcache:list

vendor/bin/typo3 temporalcache:list --table=pages --upcoming --sort=starttime --limit=10

vendor/bin/typo3 temporalcache:list --format=csv > temporal-content.csv

vendor/bin/typo3 temporalcache:list --format=json > temporal-content.json

temporalcache:harmonize 

Rounds starttime and endtime values to the configured time slots, so that fewer distinct transition timestamps remain and the cache is invalidated less often.

This is the only command that changes data.

vendor/bin/typo3 temporalcache:harmonize --dry-run

vendor/bin/typo3 temporalcache:harmonize --dry-run --verbose

vendor/bin/typo3 temporalcache:harmonize --table=pages

Next steps 

• Configuration — extension configuration reference, including the harmonization slots and tolerance that temporalcache:harmonize reads
• Backend module — the same data in the TYPO3 backend
• TYPO3 Reports module — status reporting inside the TYPO3 Reports module

System status report 

The Temporal Cache extension contributes five status entries to TYPO3's built-in Reports module.

Report sections 

Common scenarios 

Automation and monitoring 

# Quick verification (exit code 0 = OK, 1 = issues)
vendor/bin/typo3 temporalcache:verify

# Verbose output for logs
vendor/bin/typo3 temporalcache:verify --verbose

#!/bin/bash
# /usr/local/nagios/libexec/check_typo3_temporal_cache.sh

cd /var/www/html/typo3
vendor/bin/typo3 temporalcache:verify >/dev/null 2>&1

if [ $? -eq 0 ]; then
    echo "OK - Temporal Cache system healthy"
    exit 0
else
    echo "CRITICAL - Temporal Cache system issues detected"
    exit 2
fi

# Check daily and email on failure
0 8 * * * cd /var/www/html/typo3 && vendor/bin/typo3 temporalcache:verify || mail -s "TYPO3 Temporal Cache Issues" admin@example.com < /dev/null

Troubleshooting 

Best practices 

Performance optimization 

Related documentation 

• Configuration: Detailed configuration options
• Command-line interface: The temporalcache:analyze, temporalcache:harmonize, temporalcache:list and temporalcache:verify commands
• Backend module: The same data in a backend module
• Performance considerations: Performance tuning guide
• Troubleshooting: General troubleshooting guide

The gap this extension fills 

TYPO3's page cache is invalidated by two mechanisms.

Event-driven invalidation

A cache entry is dropped when the data behind it changes, for example when an editor saves a page.

Tag-based invalidation

flushByTag() drops every entry carrying a given tag.

Neither reacts to the passage of time. A page or content element with starttime or endtime changes its visibility at a fixed moment without anybody editing a record, so no invalidation is triggered. The cache entry keeps the visibility snapshot taken at render time until its relative lifetime runs out.

Render at 09:00           Cache entry written with a relative lifetime
├─ element A: hidden      (starttime 10:00 has not been reached)
└─ element B: visible

10:00                     Nothing edits a record, so nothing invalidates
                          the entry. Element A stays hidden until the
                          lifetime expires.

The extension closes that gap by shortening the page cache lifetime so it ends at the next temporal transition instead of at an arbitrary later moment.

Entry point: the cache lifetime event 

TYPO3 dispatches TYPO3\CMS\Frontend\Event\ModifyCacheLifetimeForPageEvent while a page cache entry is being written. Netresearch\TemporalCache\EventListener\TemporalCacheLifetime is registered for exactly that event class in Configuration/Services.yaml, and it is the extension's only frontend hook.

final class TemporalCacheLifetime
{
    public function __construct(
        private readonly ExtensionConfiguration $extensionConfiguration,
        private readonly ScopingStrategyInterface $scopingStrategy,
        private readonly TimingStrategyInterface $timingStrategy,
        private readonly Context $context,
        private readonly LoggerInterface $logger
    ) {
    }

    public function __invoke(ModifyCacheLifetimeForPageEvent $event): void
    {
        $lifetime = $this->timingStrategy->getCacheLifetime($this->context, $event->getPageId());

        if ($lifetime !== null) {
            $maxLifetime = $this->determineMaxLifetime($event->getRenderingInstructions());
            $event->setCacheLifetime(\min($lifetime, $maxLifetime));
        }
    }
}

The listener runs no queries of its own. It asks the active timing strategy for a lifetime and caps the answer. A null lifetime — what the scheduler timing strategy always returns — leaves TYPO3's own lifetime untouched.

The whole __invoke() body is wrapped in a try/catch (Throwable). A failing strategy is logged as an error and the page renders with TYPO3's lifetime; it never breaks page rendering.

services:
  Netresearch\TemporalCache\EventListener\TemporalCacheLifetime:
    public: true
    tags:
      - name: event.listener
        identifier: 'temporal-cache/modify-cache-lifetime'
        event: TYPO3\CMS\Frontend\Event\ModifyCacheLifetimeForPageEvent
        method: '__invoke'

Strategy selection and wiring 

Two independent strategy families decide what happens:

Scoping strategy (ScopingStrategyInterface)

Answers which records a transition lookup covers and which cache tags a transition flushes. Implementations: GlobalScopingStrategy, PerPageScopingStrategy, PerContentScopingStrategy.

Timing strategy (TimingStrategyInterface)

Answers when the invalidation happens — through a shortened cache lifetime, through a background scheduler run, or a mix of the two. Implementations: DynamicTimingStrategy, SchedulerTimingStrategy, HybridTimingStrategy.

Both interfaces extend Netresearch\TemporalCache\Service\NamedStrategyInterface, which declares the single method getName(): string.

Netresearch\TemporalCache\Service\Scoping\ScopingStrategyFactory:
  public: true
  arguments:
    $strategies: !tagged_iterator 'nr_temporal_cache.scoping_strategy'
    $extensionConfiguration: '@Netresearch\TemporalCache\Configuration\ExtensionConfiguration'

Netresearch\TemporalCache\Service\Scoping\ScopingStrategyInterface:
  alias: Netresearch\TemporalCache\Service\Scoping\ScopingStrategyFactory
  public: false

private function selectNamedStrategy(
    iterable $strategies,
    string $configuredName,
    string $emptyMessage
): NamedStrategyInterface {
    $firstStrategy = null;

    foreach ($strategies as $strategy) {
        $firstStrategy ??= $strategy;

        if ($strategy->getName() === $configuredName) {
            return $strategy;
        }
    }

    return $firstStrategy ?? throw new RuntimeException($emptyMessage);
}

namespace MyVendor\MyExtension\Scoping;

use Netresearch\TemporalCache\Domain\Model\TemporalContent;
use Netresearch\TemporalCache\Service\Scoping\ScopingStrategyInterface;
use TYPO3\CMS\Core\Context\Context;

final class RootlineScopingStrategy implements ScopingStrategyInterface
{
    public function getCacheTagsToFlush(TemporalContent $content, Context $context): array
    {
        return ['pageId_' . $content->pid];
    }

    public function getNextTransition(Context $context, ?int $pageId = null): ?int
    {
        return null;
    }

    public function getName(): string
    {
        return 'rootline';
    }
}

services:
  MyVendor\MyExtension\Scoping\RootlineScopingStrategy:
    tags:
      - { name: 'nr_temporal_cache.scoping_strategy' }

Transition lookups 

All temporal queries live in Netresearch\TemporalCache\Domain\Repository\TemporalContentRepository (contract: TemporalContentRepositoryInterface). Three methods feed the strategies:

// Earliest transition across every monitored table (site-wide)
public function getNextTransition(
    int $currentTimestamp,
    int $workspaceUid = 0,
    int $languageUid = 0
): ?int;

// Earliest transition in the pages table only
public function getNextPageTransition(
    int $currentTimestamp,
    int $workspaceUid = 0,
    int $languageUid = 0
): ?int;

// Earliest transition in the content tables, restricted to one pid
public function getNextContentTransitionForPage(
    int $pageId,
    int $currentTimestamp,
    int $workspaceUid = 0,
    int $languageUid = 0
): ?int;

Each of them runs one MIN() query per monitored table and per temporal field (starttime, endtime) and returns the smallest non-null result. With the two default tables that is four queries.

findMinTransitionForTable() builds every query the same way:

• removeAll() on the restrictions. TYPO3's StartTimeRestriction/EndTimeRestriction would hide exactly the future records the lookup needs.
• MIN(<field>) selected as a literal, WHERE <field> > :now. Records with 0 are excluded by that comparison, so no separate != 0 clause exists.
• The table's deleted and disabled columns, resolved from TCA, each compared to 0. When no TCA is available the query simply runs without them.
• pid = :pageId when the caller passed a page id.
• The workspace clause: for workspace 0 it matches `t3ver_wsid = 0 OR t3ver_wsid IS NULL``, otherwise ``t3ver_wsid = :workspace`.
• sys_language_uid = :language whenever the language id is >= 0.

What each scoping strategy does 

A scoping strategy answers two separate questions, and the answers do not have to agree.

getNextTransition()

Used by DynamicTimingStrategy to compute a cache lifetime.

getCacheTagsToFlush()

Used by SchedulerTimingStrategy to flush caches from the scheduler task. DynamicTimingStrategy never calls it.

What each timing strategy does 

Workspace and language awareness 

All three scoping strategies read the current context through the trait Netresearch\TemporalCache\Service\Scoping\ResolvesContextAspects:

$workspaceId = $context->getPropertyFromAspect('workspace', 'id', 0);
$languageId = $context->getPropertyFromAspect('language', 'id', 0);

Both values are passed down into every query, so a workspace preview and each language resolve their own next transition and therefore their own cache lifetime. One frontend request carries one workspace and one language, so the number of queries does not grow with the number of languages configured on the site.

Extensibility 

namespace MyVendor\MyExtension\Service;

use Netresearch\TemporalCache\Service\TemporalMonitorRegistry;

final class NewsTemporalRegistration
{
    public function __construct(
        private readonly TemporalMonitorRegistry $monitorRegistry
    ) {
        $this->monitorRegistry->registerTable(
            'tx_news_domain_model_news',
            ['uid', 'pid', 'title', 'starttime', 'endtime', 'hidden', 'deleted', 'sys_language_uid']
        );
    }
}

namespace MyVendor\MyExtension\EventListener;

use TYPO3\CMS\Frontend\Event\ModifyCacheLifetimeForPageEvent;

final class CustomTemporalLogic
{
    public function __invoke(ModifyCacheLifetimeForPageEvent $event): void
    {
        $customTransition = $this->getCustomTransition($event->getPageId());

        if ($customTransition !== null) {
            $event->setCacheLifetime(
                \min($event->getCacheLifetime(), \max(0, $customTransition - \time()))
            );
        }
    }

    private function getCustomTransition(int $pageId): ?int
    {
        return null;
    }
}

services:
  MyVendor\MyExtension\EventListener\CustomTemporalLogic:
    tags:
      - name: event.listener
        identifier: 'my-extension/custom-temporal-logic'
        event: TYPO3\CMS\Frontend\Event\ModifyCacheLifetimeForPageEvent
        after: 'temporal-cache/modify-cache-lifetime'

Known limitations 

Only the page cache is addressed

The listener sets the page cache lifetime. Other caches keep whatever lifetime their own code assigns.

Per-second granularity

Transitions are Unix timestamps; nothing finer is possible.

No cross-page dependency detection with dynamic timing

per-page scoping does not shorten a page's lifetime for content embedded from elsewhere, and per-content scoping only narrows flush tags.

Scheduler timing flushes only what the scoping strategy names

With per-page or per-content scoping a page transition flushes only that page's own tag, so menus on other pages are not refreshed by the scheduler run. global scoping flushes the pages tag and does refresh them.

Additional tables get no indexes

ext_tables.sql covers pages and tt_content. A registered table needs its own index on starttime and endtime.

Next steps 

• Performance considerations — configuration trade-offs
• Configuration — every option in detail
• Approach, limits and a core solution — where this approach sits relative to a core solution
• Source code
• Forge #14277 — the core issue

Overview 

This chapter explains why the extension works the way it does, what the approach cannot do, and what a solution inside TYPO3 core would have to provide to make the extension unnecessary.

Nothing here describes committed work in TYPO3 core. There is no accepted RFC, no target version and no timeline for a core solution; treat the section on it as a description of the missing capability, not as a roadmap.

What the extension does today 

TYPO3's cache API accepts a relative lifetime — "keep this for N seconds". It has no absolute expiration — "keep this until timestamp T". Temporal visibility is an absolute-expiration problem, so the extension approximates one in two ways.

Shorten the lifetime (timing.strategy = dynamic)

The listener on ModifyCacheLifetimeForPageEvent computes nextTransition - time() and sets that as the entry's lifetime.

public function __invoke(ModifyCacheLifetimeForPageEvent $event): void
{
    $lifetime = $this->timingStrategy->getCacheLifetime($this->context, $event->getPageId());

    if ($lifetime !== null) {
        $maxLifetime = $this->determineMaxLifetime($event->getRenderingInstructions());
        $event->setCacheLifetime(\min($lifetime, $maxLifetime));
    }
}

Flush tags from a scheduled task (timing.strategy = scheduler)

The listener leaves the lifetime alone. TemporalCacheSchedulerTask asks for every transition since its last run and flushes the cache tags the scoping strategy names for each of them.

hybrid combines the two, choosing per record type. See What each timing strategy does for the exact behavior of each strategy.

What a core solution would need 

Two capabilities are missing from TYPO3, and both would have to come from core.

If core gains these capabilities 

Nothing in this extension currently detects core capabilities or switches APIs automatically; that would have to be built when there is an API to build against.

What would happen in practice:

1. The extension would gain support for the new API on the TYPO3 versions that have it, keeping the current implementation for the versions that do not.
2. Once every supported TYPO3 version carried the core solution, the extension would have nothing left to do and could be removed from a project.

Until then, the settings described in Configuration are the only lever.

When this approach fits 

It fits when

Temporal content exists and stale menus or stale content elements are a real editorial problem; and the cache behavior of the chosen configuration has been measured on the site in question.

It does not fit when

No record uses starttime/endtime — the extension then only adds queries; or the site cannot absorb the cache churn of the configuration it needs and no scoping/timing combination brings it down far enough.

Both cases are judgment calls about a specific site. Decision guide walks through which configuration matches which shape of site, and Alternative approaches covers approaches that do not involve this extension.

Feedback 

The interesting feedback for this problem is the concrete behavior of a real site: which scoping and timing combination was chosen, and what happened to the cache hit ratio.

• Forge #14277 — the core issue
• Issue tracker — bugs and feature requests for this extension

Next steps