webprofil/wp-debug

WEBprofil Debug commands for request and TypoScript

13.0.0 2026-04-13 15:01 UTC

Requires

• typo3/cms-core: ^13.0
• typo3/cms-frontend: ^13.0

GPL-2.0-or-later

README

wp_debug is a TYPO3 extension that adds CLI commands for inspecting frontend routing, active TypoScript, and loaded TCA.

It is built for developers who need quick insight into how TYPO3 resolves a request and which configuration is effectively active at runtime.

It is maintained by WEBprofil and used in production TYPO3 projects where reproducible debugging output is essential.

Why this extension exists

TYPO3 debugging often requires jumping between backend modules, configuration files, and runtime context.

wp_debug provides one place for this in the command line:

• verify how a URL/path is matched to site + language + page arguments
• inspect active TypoScript templates, include tree, and selected setup paths
• dump currently loaded TCA for one or more tables
• inspect logs from sys_log and var/log in one compact command
• output as human-readable CLI, JSON, or TOON (Token-Oriented Object Notation)

This makes troubleshooting faster in local development and staging environments.

Requirements

• TYPO3 v13
• PHP 8.3+

Installation

composer require webprofil/wp-debug

Then clear caches:

vendor/bin/typo3 cache:flush

Available commands

wp:debug:request

Debug frontend request routing for a URL or path.

Examples:

vendor/bin/typo3 wp:debug:request /seminars
vendor/bin/typo3 wp:debug:request https://example.test/en/events?tx_news_pi1%5Bnews%5D=42 --json
vendor/bin/typo3 wp:debug:request /seminars --site=main --language=1

wp:debug:typoscript

Inspect active TypoScript for a frontend page, including templates, include trees, and effective setup/config.

Examples:

vendor/bin/typo3 wp:debug:typoscript /events
vendor/bin/typo3 wp:debug:typoscript /events --show=all --json
vendor/bin/typo3 wp:debug:typoscript /events --active-json --active-tree --path=lib.header
vendor/bin/typo3 wp:debug:typoscript /events --probe=plugin.tx_site.settings.apiBaseUrl

wp:debug:tca

Inspect loaded TCA globally or for specific tables.

Examples:

vendor/bin/typo3 wp:debug:tca
vendor/bin/typo3 wp:debug:tca --table=tt_content --table=pages --json

wp:debug:logs:list

List available log sources from database and var/log.

Examples:

vendor/bin/typo3 wp:debug:logs:list
vendor/bin/typo3 wp:debug:logs:list --json

wp:debug:logs:read

Read merged log events from sys_log and var/log with compact token-friendly output.

Default behavior:

• source: all (database + files)
• since: 15m
• levels: error,warning
• format: short
• dedupe: enabled (group-by=fingerprint)
• mode: best-effort (source errors shown in output)
• tail/follow: supported for file logs and polling for sys_log (--tail, --follow)

Examples:

vendor/bin/typo3 wp:debug:logs:read
vendor/bin/typo3 wp:debug:logs:read --source=file --since=2h --limit=100
vendor/bin/typo3 wp:debug:logs:read --source=file --tail=30
vendor/bin/typo3 wp:debug:logs:read --source=file --tail=20 --follow
vendor/bin/typo3 wp:debug:logs:read --source=db --tail=20 --follow
vendor/bin/typo3 wp:debug:logs:read --source=all --tail=20 --follow
vendor/bin/typo3 wp:debug:logs:read --context=exception --search="No page configured"
vendor/bin/typo3 wp:debug:logs:read --format=json
vendor/bin/typo3 wp:debug:logs:read --strict

Output formats

• default: formatted console output for quick reading
• --json: machine-readable output for integrations
• --toon: compact structured format (TOON)

For wp:debug:logs:read, you can also use --format=short|json|toon.

LLM and agent workflows

wp_debug works well as a foundation for LLM-based debugging assistants because it provides deterministic CLI output that can be fed into prompts.

Typical pattern:

1. Let the model run wp:debug:request to verify routing assumptions.
2. Let the model run wp:debug:typoscript to inspect active setup/config values.
3. Let the model run wp:debug:tca when backend form behavior is suspicious.
4. Let the model run wp:debug:logs:read for recent runtime errors.
5. Return a diagnosis plus next actions based on the command output.

A ready-to-use skill template is included in this package:

• packages/wp-debug/SKILL.md

If you build internal AI workflows around TYPO3 support, wp_debug gives your prompts a reliable, low-noise source of runtime truth.

Typical use cases

• route enhancer does not match as expected
• wrong site/language is selected for a path
• TypoScript condition or include order issue
• plugin settings seem different from expected setup
• TCA overrides from extensions need verification

License

GPL-2.0-or-later