141 lines
7.0 KiB
Markdown
141 lines
7.0 KiB
Markdown
# 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:
|
||
|
||
```bash
|
||
command -v xtrace xstep xprofile xcoverage xback
|
||
```
|
||
|
||
If Composer global binaries are not on `PATH`, locate them with:
|
||
|
||
```bash
|
||
composer global config bin-dir --absolute --quiet
|
||
```
|
||
|
||
Installation, only when explicitly requested:
|
||
|
||
```bash
|
||
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
|
||
|
||
1. Resolve the project slug, local URL, and local path with `references/wp-project.md` conventions.
|
||
2. 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.
|
||
3. 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`.
|
||
4. Run the smallest safe command that captures runtime data.
|
||
5. Analyze the JSON output and inspect source files as needed.
|
||
6. Iterate with narrower breakpoints/traces until the cause is clear.
|
||
7. Report evidence: command shape, breakpoint/trace target, observed runtime data, conclusion, and any blockers.
|
||
|
||
## Example commands
|
||
|
||
Script or isolated command:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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.
|
||
|
||
```bash
|
||
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.
|