Debug test runnables through the Xdebug adapter

[roxblnfk]

What

Lets you debug PHP test runnables with the bundled Xdebug adapter: the gutter now offers Debug next to Run for the PHPUnit/Pest runnables (and any php <script> task), launching the exact test under the cursor with breakpoints. It also enables Xdebug's listen mode for debugging incoming web requests.

The extension already ships the Xdebug debug adapter, but nothing connected it to the runnable tasks, and the PHP language wasn't associated with any debugger — so no debug affordance ever appeared. This PR wires that up.

How

• Language ↔ adapter. languages/php/config.toml gains debuggers = ["Xdebug"]. Without this, code_actions.rs::debug_scenarios bails out early (no default debug adapter for the buffer) and never reaches a locator.
• Debug locator. A new [debug_locators.php] and dap_locator_create_scenario turn a runnable task into an Xdebug launch scenario. It drops the php wrapper to find the program, strips the double quotes tasks.json adds for the "Run" shell (the adapter spawns argv directly, without a shell), and skips inline php -r code.
• Launch-config fixups at spawn time (get_installed_binary, the single choke point every scenario passes through — gutter, debug.json, F4). These apply only when the config has a program (a CLI launch); see listen mode below:
  • cwd → worktree root (a locator scenario carries "cwd": null, which entry(..).or_insert wouldn't fill);
  • runtimeExecutable → absolute php, via a PHP_BINARY env override then which("php"), because spawn("php") can't resolve a bare name on Windows;
  • runtimeArgs → -dxdebug.mode=debug -dxdebug.start_with_request=yes -dxdebug.client_port=${port}. The adapter forwards runtimeArgs to PHP verbatim and never enables Xdebug itself, so without these the launched script never connects back. ${port} is replaced by the adapter with the DBGp port it listens on, so it always matches. A user's own runtimeArgs take precedence.
  • When php resolves to a .bat/.cmd shim, fail with an actionable message instead of the cryptic spawn EINVAL Node throws for batch files (CVE-2024-27980).
• Schema. debug_adapter_schemas/Xdebug.json documents runtimeExecutable and runtimeArgs, so they autocomplete when editing .zed/debug.json.

Listen mode (debugging web requests)

The same adapter listens for incoming Xdebug connections when a launch config has no program — the usual workflow for debugging a request triggered from the browser or an external CLI run. Because the spawn-time fixups above are gated on program, a program-less config is left untouched: the adapter listens instead of trying to spawn php with no script, and the .bat/.cmd guard doesn't reject a session that never launches PHP.

Set it up:

1. Add a program-less scenario to .zed/debug.json:

   [{ "adapter": "Xdebug", "label": "Listen for Xdebug", "request": "launch" }]

2. Open debugger: start, pick Listen for Xdebug from the list and start it. The session now listens on the DBGp port (9003 by default; set "port" in the config to change it) — no executable to fill in.

3. Set your breakpoints.

4. Run PHP with Xdebug pointed at the listener, e.g.:

   php -dxdebug.mode=debug -dxdebug.start_with_request=yes \
       -dxdebug.client_host=127.0.0.1 -dxdebug.client_port=9003 \
       vendor/bin/phpunit
   

   or configure the same via php.ini / XDEBUG_MODE=debug and just trigger a web request. Xdebug connects back to the listening session and breakpoints bind.

Requirements

Breakpoints require Xdebug to be loaded in the PHP that runs (via zend_extension); the -dxdebug.* overrides only configure an already-installed Xdebug, they don't load it.

Tests

Unit tests in src/xdebug.rs cover the locator: the testo/phpunit program split, quote stripping, declining inline code, and declining other adapters. cargo test, cargo fmt --check and cargo clippy --all-features -- -D warnings (wasm target) are green.