Architecture 

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