Debug PHP in browser Devtools (XDebug <-> CDP Bridge)

[adamziel]

Motivation for the change, related issues

An XDebug <-> CDP bridge to debug PHP code in the browser:

CleanShot.2025-06-19.at.01.59.06.mp4

Implementation details

I've asked o3-pro to build it, applied a few tweaks, and voila – we have a a demo :-)

Testing Instructions (or ideally a Blueprint)

• Apply the JSPI PR and this PR.
• Make sure you're running Node v23+
• Run:

node --experimental-wasm-stack-switching --experimental-wasm-jspi --loader=./packages/meta/src/node-es-module-loader/loader.mts  packages/xdebug/protocol.ts

The script will guide you from there

Problems

When eval is called, PHP crashes like below. It may be a bridge problem or XDebug problem:

[XDebug][send] eval -- JGNvbnN0cw==
Error: resolved is not a function
    at runExecutionFunction (file:///Users/cloudnik/www/Automattic/core/plugins/playground/packages/php-wasm/universal/src/lib/php.ts:971:22) {
  cause: TypeError: resolved is not a function
      at stubs.<computed> (file:///Users/cloudnik/www/Automattic/core/plugins/playground/packages/php-wasm/node/jspi/php_8_4.js:1296:15)
      at wasm://wasm/000ef1e6:wasm-function[545]:0x203cc
      at wasm://wasm/000ef1e6:wasm-function[604]:0x26320
      at wasm://wasm/000ef1e6:wasm-function[574]:0x228d0
      at wasm://wasm/000ef1e6:wasm-function[578]:0x232ca
      at wasm://wasm/000ef1e6:wasm-function[549]:0x20966
      at wasm://wasm/000ef1e6:wasm-function[219]:0xa209
      at php.wasm.zend_extension_statement_handler (wasm://wasm/php.wasm-08a18d7a:wasm-function[9230]:0x77b902)
      at php.wasm.zend_llist_apply_with_argument (wasm://wasm/php.wasm-08a18d7a:wasm-function[10088]:0x7ee577)
      at php.wasm.ZEND_EXT_STMT_SPEC_HANDLER (wasm://wasm/php.wasm-08a18d7a:wasm-function[9229]:0x77b8df)
}
node:internal/process/promises:394
    triggerUncaughtException(err, true /* fromPromise */);
    ^

Error: resolved is not a function
    at runExecutionFunction (file:///Users/cloudnik/www/Automattic/core/plugins/playground/packages/php-wasm/universal/src/lib/php.ts:971:22) {
  cause: TypeError: resolved is not a function
      at stubs.<computed> (file:///Users/cloudnik/www/Automattic/core/plugins/playground/packages/php-wasm/node/jspi/php_8_4.js:1296:15)
      at wasm://wasm/000ef1e6:wasm-function[545]:0x203cc
      at wasm://wasm/000ef1e6:wasm-function[604]:0x26320
      at wasm://wasm/000ef1e6:wasm-function[574]:0x228d0
      at wasm://wasm/000ef1e6:wasm-function[578]:0x232ca
      at wasm://wasm/000ef1e6:wasm-function[549]:0x20966
      at wasm://wasm/000ef1e6:wasm-function[219]:0xa209
      at php.wasm.zend_extension_statement_handler (wasm://wasm/php.wasm-08a18d7a:wasm-function[9230]:0x77b902)
      at php.wasm.zend_llist_apply_with_argument (wasm://wasm/php.wasm-08a18d7a:wasm-function[10088]:0x7ee577)
      at php.wasm.ZEND_EXT_STMT_SPEC_HANDLER (wasm://wasm/php.wasm-08a18d7a:wasm-function[9229]:0x77b8df)
}

Node.js v23.11.0

cc @mho22 @brandonpayton @akirk @wojtekn @griffbrad @bgrgicak

[mho22]

@adamziel I'm impressed. A great way to begin my day. I need to dive deeper into that protocol.

[brandonpayton]

@adamziel, this looks awesome!

[adamziel]

Or should we do WebDriver BiDi instead? Firefox is retiring its CDP support:

https://fxdx.dev/cdp-retirement-in-firefox/

And if you are migrating a tool from CDP to WebDriver BiDi for Firefox, you should also consider using WebDriver BiDi for Chromium based browsers. Chromium has a great support for WebDriver BiDi, and WebKit is starting to implement BiDi as well. So switching to BiDi now is not only a way to keep Firefox support, but it can also pave the way to get more features for all browsers as we keep expanding the standard protocol.