WP Xdebug

Use this skill when the agent should debug local Websimple WordPress PHP execution autonomously. Prefer references/wp-project.md first when you need to resolve the site slug, local URL, or project path. Use references/wp-browser.md only when browser interaction is needed to understand or reproduce the behavior.

The expected path is autonomous debugging with koriym/xdebug-mcp; do not require the user to have VS Code open or listening for Xdebug connections.

Scope and safety

Use Xdebug only for local Websimple development sites unless the user explicitly confirms otherwise.
Do not install tools, enable/reconfigure Xdebug, restart services, or modify project files unless requested.
Avoid sending public/production form submissions or external-effect requests while debugging.
Prefer deterministic local reproductions: PHP script, WP-CLI command, PHPUnit command, safe curl/API request, or a minimal reproducer.
If autonomous runtime debugging cannot be performed because xdebug-mcp or Xdebug is missing, report that as a blocker and suggest the smallest next setup step.

Required autonomous debugger

Use koriym/xdebug-mcp to provide Xdebug-backed tools with structured JSON output for AI analysis:

xtrace: trace execution flow.
xstep: stop at breakpoints and inspect variables.
xprofile: collect performance profiling data.
xcoverage: collect coverage data.
xback: capture call stack/backtrace at a breakpoint.
xcompare: compare variable states across runs; CLI-only.

Check availability before relying on it:

command -v xtrace xstep xprofile xcoverage xback

If Composer global binaries are not on PATH, locate them with:

composer global config bin-dir --absolute --quiet

Installation, only when explicitly requested:

composer global require koriym/xdebug-mcp

Preconditions

Before triggering a debug run, confirm or infer:

The target is local code/site, normally ${WEBSIMPLE_STACK_PROTOCOL}://${slug}.${WEBSIMPLE_STACK_DOMAIN} and ${WP_LOCAL_ROOT_PATH}/${slug}.
Xdebug 3.x is installed for the PHP runtime used by the debug command.
xdebug-mcp CLI tools are available, or MCP exposes the equivalent tools.
The reproduction command actually executes the PHP code being investigated.

For Websimple WordPress, remember that the served document root inside the PHP container is normally /var/www/html; map that mentally to the local WordPress project root when interpreting file paths.

Autonomous workflow

Resolve the project slug, local URL, and local path with references/wp-project.md conventions.
Identify the code path and the safest reproduction strategy:
- WP-CLI command when WordPress bootstrap/state is needed.
- PHP script or small throwaway reproducer for isolated functions/classes.
- PHPUnit or project test command when a test exists.
- curl/API request only when it safely and actually triggers the PHP code under debug.
- Browser only to discover state, cookies, nonces, or the user flow; then reduce to a deterministic command when possible.
Pick the xdebug-mcp tool:
- Need execution path? Use xtrace.
- Need variable state at a line? Use xstep --break='file.php:line'.
- Need caller chain? Use xback --break='file.php:line'.
- Need slowness data? Use xprofile --json.
- Need coverage? Use xcoverage.
Run the smallest safe command that captures runtime data.
Analyze the JSON output and inspect source files as needed.
Iterate with narrower breakpoints/traces until the cause is clear.
Report evidence: command shape, breakpoint/trace target, observed runtime data, conclusion, and any blockers.

Example commands

Script or isolated command:

xtrace -- php path/to/script.php
xstep --break='path/to/file.php:42' -- php path/to/script.php
xback --break='path/to/file.php:42' -- php path/to/script.php
xprofile --json -- php path/to/script.php

WP-CLI reproduction from the local WordPress root. When using the /usr/local/bin/wp PHAR, invoke it explicitly through PHP so xdebug-mcp can determine the target script:

cd "${WP_LOCAL_ROOT_PATH}/${slug}"
xtrace -- php /usr/local/bin/wp --path="${WP_LOCAL_ROOT_PATH}/${slug}" eval '/* minimal safe reproduction */'
xstep --break='wp-content/themes/theme/file.php:42' -- php /usr/local/bin/wp --path="${WP_LOCAL_ROOT_PATH}/${slug}" eval '/* minimal safe reproduction */'
xback --break='wp-content/themes/theme/file.php:42' -- php /usr/local/bin/wp --path="${WP_LOCAL_ROOT_PATH}/${slug}" eval '/* minimal safe reproduction */'

Test reproduction:

xtrace -- vendor/bin/phpunit --filter 'RelevantTest'
xcoverage -- vendor/bin/phpunit --filter 'RelevantTest'

Containerized reproduction, if the PHP code must run inside the Websimple stack, should use the actual service names after inspection. Standard PHP is wp-php; browser-triggered Xdebug requests are routed to wp-php-xdebug when the XDEBUG_SESSION=vscode cookie is present.

xtrace -- docker compose exec -T wp-php php /var/www/html/${slug}/path/to/script.php
xstep --break='/var/www/html/${slug}/wp-content/themes/theme/file.php:42' -- docker compose exec -T wp-php php /var/www/html/${slug}/path/to/script.php

Only use command forms that match the actual Websimple stack project layout after inspecting the project/stack.

Browser and HTTP flows

For browser-only bugs:

Use references/wp-browser.md to reproduce the UI and inspect the request details.
Avoid relying on a human IDE listener.
Prefer converting the observed request into a safe deterministic command: WP-CLI, script, test, or curl with required cookies/nonces.
Be careful: wrapping curl with xtrace only debugs PHP if the Xdebug capture is attached to the PHP runtime handling the request. If the PHP executes in Apache/FPM separately, use a supported xdebug-mcp/container strategy or reduce the behavior to WP-CLI/script instead.

Do not use Xdebug triggers on production/remote URLs.

Common WordPress targets

Frontend template load: theme template, template_redirect, query hooks, block rendering.
wp-admin page: menu page callbacks, list tables, metaboxes, save handlers.
REST API: route callback and permission callback.
admin-ajax: wp_ajax_* / wp_ajax_nopriv_* handlers.
Forms: validation/submission hooks, but do not submit externally-effectful forms unless explicitly requested.
Cron-like handlers: only trigger explicitly requested local code paths; do not run destructive jobs by accident.

Troubleshooting

If no runtime data appears:

Confirm xtrace/xstep/xback is installed and on PATH.
Confirm the command after -- actually runs PHP and reaches the code path.
Confirm Xdebug 3.x is installed for that PHP binary/container.
Confirm paths in breakpoints match the runtime paths shown in traces, often /var/www/html/... inside containers.
Confirm the request/command is local, not production.
If browser navigation is blocked by policy, use references/wp-browser.md’s browser SSRF prerequisite for ${WEBSIMPLE_STACK_DOMAIN} local sites.

7.0 KiB Raw Blame History Unescape Escape