Download the PHP package konradmichalik/typo3-request-profiler without Composer

A dev-only TYPO3 frontend request profiler. It instruments live frontend requests and writes one compact JSON profile per request — SQL queries, N+1 patterns, cache state, and timing — to var/log/profiles/{request_id}.json.

[!IMPORTANT] This extension is active by default only in a Development context (Environment::getContext()->isDevelopment()). Outside Development it stays off and collects no data unless explicitly opted in via TYPO3_REQUEST_PROFILER_FORCE=1 (intended for staging, never real production — see Configuration).

The profiler is a thin, standalone collector with no external dependencies. It is inspired by the Symfony Profiler — and by some of the metrics the TYPO3 Admin Panel surfaces — but records them as compact, machine-readable JSON instead of an interactive panel.

What it captures per request:

• Wall-clock and SQL timing, peak memory usage, included PHP file count
• Full query count + top slow queries + N+1 duplicate detection
• Cache hit/miss state with disabled reasons
• Log activity per request (count by level + noisiest components)
• Optional call-site origin (Class::method (file:line)) for every flagged query

🔥 Installation

Requirements

• TYPO3 13.4 LTS & 14.0+
• PHP 8.2+
• Doctrine DBAL 3.x or 4.x

Composer

TER

Download the zip file from TYPO3 extension repository (TER).

⚙️ Configuration

The profiler is controlled entirely via environment variables:

[!NOTE] TYPO3_REQUEST_PROFILER_FORCE is a deployment-level switch evaluated in ext_localconf.php and therefore cached — it is not a live toggle. Changing it requires a cache flush to take effect. This is in contrast to the per-request TYPO3_REQUEST_PROFILER=0, which short-circuits the middleware on each request and needs no cache flush.

[!TIP] TYPO3_REQUEST_PROFILER_TRACE=1 uses debug_backtrace per query and is therefore opt-in for performance. No bound parameter values are ever captured — only the call site.

[!TIP] TYPO3_REQUEST_PROFILER_EVENTS=1 wraps the core PSR-14 dispatcher and measures every dispatched event. Dispatch happens very frequently, so the per-event timing is opt-in. When off, events are dispatched without any measurement and the events section is omitted. Event timing follows the same activation gate as the rest of the profiler, so it also works on staging together with TYPO3_REQUEST_PROFILER_FORCE=1.

💡 Profile Format

Each request produces one JSON file at var/log/profiles/{request_id}.json:

[!NOTE] The log section only appears when the request produced log entries. Only the level and component are recorded — never the message body — so no user data leaks into the profile.

[!NOTE] The events section only appears when TYPO3_REQUEST_PROFILER_EVENTS=1.

Profile schema

The artifact carries an explicit, versioned schema contract via the top-level schemaVersion field. It is written first so it is immediately visible in every file.

Top-level fields (always present):

Section keys (key = Section::name(); each appears only when the section is enabled and produced data):

[!NOTE] schemaVersion is incremented only when field names or shapes change in a breaking way. Additive changes keep the same version.

Reading profiles

KonradMichalik\Typo3RequestProfiler\Profiling\ProfileReader is the supported, framework-agnostic read API for these artifacts — external consumers should use it instead of re-implementing the glob/sort/json_decode logic:

The reader is directory-based and carries no framework dependency — its constructor takes the profiles directory (new ProfileReader($directory)). On the TYPO3 side, that directory is ProfileWriter::defaultDirectory() (the same source the writer persists to). Its public signature is kept stable as a contract for consumers.

🧑‍💻 Contributing

Please have a look at CONTRIBUTING.md.

⭐ License

This project is licensed under GNU General Public License 2.0 (or later).