moselwal/frankenphp — worker mode plus Souin cache for TYPO3.

Five building blocks

• FrankenPHP frontend worker — request classification separates frontend requests (worker mode) from backend and install tool. The worker bootstraps TYPO3 fresh per request, no state sharing between requests.
• 103 Early Hints — actual RFC 8297 responses via headers_send(103) from the AssetCollector. CSS and JS preloads start in parallel with server rendering.
• Caddy/Souin cache invalidation — REST-API based via PURGE and DELETE. Three strategies: URL-based, tag-based via Surrogate-Key, wildcard.
• PSR-14 event architecture plus DataHandler hook — auto-invalidation on page, content and file changes.
• Backend module — Admin Tools → manual flushes and cache-key inspection.

Requirements

• TYPO3 13.4 or 14.x
• PHP 8.3+
• FrankenPHP 1.x
• Caddy 2.11+ with cache-handler / Souin
• Extension key frankenphp, namespace Moselwal\FrankenPHP, GPL-2.0-or-later

Frontend worker and request classification

Classes/Runtime/ is excluded from DI auto-registration because this code runs before the TYPO3 container.

Environment variables

Cache invalidation against Caddy/Souin

CaddyCacheService speaks the Souin REST API:

• DELETE{proto}://{host}:{port}{apiEndpoint} with JSON body {"url": "https://example.com/path"} — URL based
• PURGE{proto}://{host}:{port}{apiEndpoint} with Surrogate-Key header — tag based
• Wildcard URLs — site wide

Auto-invalidation

• PSR-14 CacheFlushEvent — general cache flush
• DataHandler hook processDatamap_afterDatabaseOperations — pages, tt_content, sys_file, sys_file_reference, fe_users, fe_groups
• PSR-14 SystemInformationToolbarCollectorEvent — backend toolbar integration

Optional API key via X-API-Key header.

Custom cache tags

$this->caddyCacheService->invalidateByTags(['custom:tag', 'product:123']);

Custom event listener

# Configuration/Services.yaml
services:
  Your\Extension\EventListener\CustomCacheListener:
    tags:
      - name: event.listener
        identifier: 'custom-cache-invalidation'
        event: Your\Extension\Event\CustomEvent

EarlyHintMiddleware (103 Early Hints)

The middleware collects the CSS and JS sources registered via the AssetCollector in the PSR-15 hook after handler->handle(), resolves EXT: paths with PathUtility::getSystemResourceUri() (TYPO3 v14+ conformant) and sends two parallel hints:

1. 103 Early Hints via headers_send(103) — as soon as FrankenPHP exposes the function (function_exists() guard for CLI and test contexts).
2. Link: header on the 200 response — fallback and for HTTP/2-push-capable reverse proxies.

Both mechanisms produce browser-deduplicable preload hints. CSS and JS heavy pages measurably improve their LCP values.

Middleware position: before typo3/cms-frontend/timetracker (see Configuration/RequestMiddlewares.php).

Installation and Caddyfile

composer require moselwal/frankenphp

Caddyfile

your-domain.com {
    root * /app/public
    
    php_server {
        worker /app/vendor/moselwal/frankenphp/Resources/Private/Worker/frontend.php
        env TYPO3_BACKEND_ENTRYPOINT /typo3
        env MAX_REQUESTS 1000
    }
    
    route {
        cache {
            api {
                souin
            }
            ttl 1h
            default_cache_control public
        }
    }
}

Extension configuration

In the TYPO3 backend under “Admin Tools → Extension Configuration → frankenphp”:

Worker reload and troubleshooting

Worker reload without a container restart

OPcache caches middleware code per worker thread. After code changes, typo3 cache:flush --group all alone is not enough — recycle the workers:

# SIGUSR1 to FrankenPHP PID 1
docker exec <httpd-container> kill -USR1 1

frankenphp reload --config /etc/caddy/Caddyfile only reloads the Caddy config, not necessarily the PHP worker threads.

Logging

PSR-3 logger via TYPO3:

• Info — normal cache invalidation operations
• Warning — failed API calls
• Error — exceptions during invalidation
• Debug — request and response details (only with enableDebugLogging)

Backend module

“Admin Tools → Caddy Cache Management”:

• Flush All Cache — invalidates all configured sites
• Flush Site Cache — per site
• Cache Status — overview of the auto-invalidation

Troubleshooting

Where we use this …

This package carries the PHP runtime in TYPO3 Kubernetes — worker mode, lower startup cost per pod, better utilisation. Managed variant: AI-Ready CMS as a Service.