# 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.