[ xdebug ] Bridge DBGP session with CDP server #2402

adamziel · 2025-07-22T14:19:29Z

Motivation for the change, related issues

Populates the new php-wasm-xdebug-bridge package which will connect Xdebug with Browser Devtools.

Roadmap

Related issues and pull requests

Implementation details

DBGP communication TCP server, which the bridge uses to communication between PHP.wasm XDebug and the CDP server. XDebug defaultly discusses on port 9003. While the DBGP server is set on port 9003 by default.
CDP Websocket Server, which communicates between the Browser Devtools and the DBGP server, with the help of a bridge. The default port is 9229.
XDebug <-> CDP Bridge, which ties the above implementations together. It plays with all the specificities of the DBGP protocol and the CDP protocol.
A startBridge function that will initialize the servers, get the soon-to-be-debugged files and return the built bridge.
A CLI tool that will start the bridge between the browser and a XDebug.

Testing Instructions

Create a xdebug.php PHP file at the root of the repository :

<?php

$test = 42;  // Set a breakpoint on this line

echo "Output!\n";

function test() {
	echo "Hello Xdebug World!\n";
}

test();

From Wordpress-Playground repository

Run the xdebug-bridge command in a first terminal :

> npx nx run php-wasm-xdebug-bridge:dev

...

Chrome connected! Initializing Xdebug receiver...
XDebug receiver running on port 9003
Running a PHP script with Xdebug enabled...

Run the php-wasm-cli command in a second terminal :

> nx run php-wasm-cli:dev --xdebug xdebug.php

Output!
Hello Xdebug World!

From non-related Playground project

Install dependencies

npm install @php-wasm/cli @php-wasm/xdebug-bridge

Run the xdebug-bridge command in a first terminal :

> npx xdebug-bridge

...

Chrome connected! Initializing Xdebug receiver...
XDebug receiver running on port 9003
Running a PHP script with Xdebug enabled...

Run the @php-wasm/cli command in a second terminal :

> npx cli --xdebug xdebug.php

Output!
Hello Xdebug World!

mho22 · 2025-07-22T16:08:51Z

I’d be happy to take over tomorrow morning, unless you get to it first!

mho22 · 2025-07-23T10:01:46Z

I implemented the build by having a look at the other packages, removing what was unnecessary and relying mainly on @wp-playground/cli since it has also two files to build. I may have made errors, don't hesitate to show them to me.

FYI, I am currently trying out the new package by running npm run local-package-repository. However, it crashes with this :

> npx xdebug-bridge

Starting XDebug Bridge...
file:///Users/mho/Work/Projects/Development/Web/Professional/xdebug/template/node_modules/@php-wasm/xdebug-bridge/cli.js:3012
    super(), this.ws = null, this.wss = new To.WebSocketServer({ port: t }), this.wss.on("connection", (e) => {
                                        ^

TypeError: To.WebSocketServer is not a constructor

While running nx run php-wasm-xdebug-bridge:dev from the current project successfully opens the devtools :

> npx nx run php-wasm-xdebug-bridge:dev

 NX   Resetting the Nx cache and stopping the daemon.



 NX   Successfully reset the Nx workspace.


> nx run php-wasm-xdebug-bridge:dev

> node --no-warnings --experimental-wasm-stack-switching --experimental-wasm-jspi --loader=./packages/meta/src/node-es-module-loader/loader.mts ./packages/php-wasm/xdebug-bridge/src/index.ts

Starting XDebug Bridge...
Connect Chrome DevTools to CDP at:
devtools://devtools/bundled/inspector.html?ws=localhost:9229

It seems to be linked with me changing target to es2020 instead of node20. I also added ws as an external dependency.

mho22 · 2025-07-23T11:15:41Z

This video says it better than a long comment could :

output.mp4

You maybe noticed the xdebug-bridge binary with the php-root absolute path option. That is because I got a duplicate directory in the devtools without it. This is probably related to dbgp using absolute paths by default, at least, when I was using it with VSCode.

There is still two checks I want to do before I think we can review the changes :

log only when verbose enabled
if php-root is relative [ and it is by default ], then dbgp should be relative

I have to dig into this as I am not sure this being possible but, let's give it a try.

mho22 · 2025-07-23T12:46:22Z

Focus on the xdebug-bridge tool inside the repository.

We need to run the following command :

> nx run php-wasm-xdebug-bridge:dev

Starting XDebug Bridge...
Connect Chrome DevTools to CDP at:
devtools://devtools/bundled/inspector.html?ws=localhost:9229

getPHPFiles was crashing on symlinks. Switching from statSync to lstatSync resolved the issue.

adamziel · 2025-07-23T21:11:10Z

Nice work @mho22!

) ## Motivation for the change, related issues This pull request adds a `--experimental-devtools` option in `wp-playground/cli`. [Roadmap](#2315) ## Related issues and pull requests - #2408 - #2402 - #2398 - #2346 - #2288 ## Implementation details - Simple implementation of a Devtools option. It checks for a `experimentalDevtools` argument that starts the `xdebug-to-cdp-bridge` process. - Changes the `StartBridgeConfig` `getPHPFile` property type from `(path: string) => string` to `(path: string) => Promise<string>` and adapt the related code. ## Testing Instructions ### In WordPress-Playground repository 1. Write a script like the following `cli.ts` : ```typescript import { runCLI } from "./packages/playground/cli/src/run-cli"; const script = ` <?php $test = 42; echo "Output!\n"; function test() { echo "Hello Xdebug World!\n"; } test(); `; const cliServer = await runCLI({command: 'server', xdebug: true, experimentalDevtools: true}); cliServer.playground.writeFile('xdebug.php', script); const result = await cliServer.playground.run({scriptPath: `xdebug.php`}); console.log(result.text); ``` 2. Run the following command : ``` > node --no-warnings --experimental-wasm-stack-switching --experimental-wasm-jspi --loader=./packages/meta/src/node-es-module-loader/loader.mts cli.ts Starting a PHP server... Setting up WordPress undefined Resolved WordPress release URL: https://downloads.w.org/release/wordpress-6.8.2.zip Fetching SQLite integration plugin... Booting WordPress... Booted! Running the Blueprint... Running the Blueprint – 100% Finished running the blueprint WordPress is running on http://127.0.0.1:61290 Connect Chrome DevTools to CDP at: devtools://devtools/bundled/inspector.html?ws=localhost:9229 ... Chrome connected! Initializing Xdebug receiver... XDebug receiver running on port 9003 Running a PHP script with Xdebug enabled... ``` ### In a non-related Playground project 1. Install dependencies ``` npm install @wp-playground/cli ``` 2. Write a script like the following `cli.ts` : ```typescript import { runCLI } from "@wp-playground/cli"; const script = ` <?php $test = 42; echo "Output!\n"; function test() { echo "Hello Xdebug World!\n"; } test(); `; const cliServer = await runCLI({command: 'server', xdebug: true, experimentalDevtools: true}); await cliServer.playground.writeFile(`xdebug.php`, script); const result = await cliServer.playground.run({scriptPath: `xdebug.php`}); console.log(result.text); ``` 3. Run command : ``` > node cli.js Starting a PHP server... Setting up WordPress undefined Resolved WordPress release URL: https://downloads.w.org/release/wordpress-6.8.2.zip Fetching SQLite integration plugin... Booting WordPress... Booted! Running the Blueprint... Running the Blueprint – 100% Finished running the blueprint WordPress is running on http://127.0.0.1:61859 Connect Chrome DevTools to CDP at: devtools://devtools/bundled/inspector.html?ws=localhost:9229 ... Chrome connected! Initializing Xdebug receiver... XDebug receiver running on port 9003 Running a PHP script with Xdebug enabled... ``` <img width="920" height="471" alt="screencapture" src="https://github.com/user-attachments/assets/b3548d0e-f824-41c4-9148-3e4f106b4116" /> Note: It will need 23 step overs before leaving the `auto_prepend_file.php` and entering the `xdebug.php` script.

XDebug <-> CDP bridge

07a90a2

mho22 mentioned this pull request Jul 22, 2025

[ php-wasm ] Follow-up on Xdebug #2315

Open

12 tasks

mho22 mentioned this pull request Jul 22, 2025

Support Xdebug #314

Open

mho22 added 3 commits July 23, 2025 09:44

Correct lint errors and warnings

57496d4

Correct merge conflicts with unneeded file index.ts

877d80e

Implement build based on other packages

a48da90

mho22 added 3 commits July 23, 2025 13:16

Corrected errors crashing built package

66a81e0

Correct error related to tests

587fee5

Focus on repository first xdebug bridge usage

90d601e

Switch statSync to lstatSync

8ff09a8

mho22 changed the title ~~XDebug <-> CDP bridge~~ [ xdebug ] Bridge DBGP session with CDP server Jul 23, 2025

mho22 added [Aspect] Browser [Feature] PHP.wasm [Type] Developer Experience [Focus] Developer Tools [Aspect] Node.js [Type] Enhancement New feature or request and removed [Aspect] Browser labels Jul 23, 2025

Improve help section

ee31029

mho22 force-pushed the port-xdebug-bridge branch from b6e4ab1 to ee31029 Compare July 23, 2025 14:45

mho22 added 3 commits July 23, 2025 16:50

Correct merge conflicts with trunk

14f2216

Correct merge conflicts with trunk

eaa48e4

Implement package building files and commands

3b7cb6c

mho22 marked this pull request as ready for review July 23, 2025 16:27

mho22 requested a review from a team as a code owner July 23, 2025 16:27

Reorganize files for next step

84caeae

mho22 mentioned this pull request Jul 23, 2025

[ xdebug ] Add --experimental-devtools option in php-wasm CLI #2408

Merged

adamziel merged commit a875920 into trunk Jul 23, 2025
24 of 25 checks passed

adamziel deleted the port-xdebug-bridge branch July 23, 2025 21:11

mho22 mentioned this pull request Jul 24, 2025

[ xdebug ] Add --experimental-devtools option in Playground CLI #2411

Merged

mho22 added the XDebug label Jul 24, 2025

fellyph mentioned this pull request Aug 4, 2025

What's new for developers? (August 2025) WordPress/developer-blog-content#381

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[ xdebug ] Bridge DBGP session with CDP server #2402

[ xdebug ] Bridge DBGP session with CDP server #2402

Uh oh!

adamziel commented Jul 22, 2025 •

edited

Loading

Uh oh!

mho22 commented Jul 22, 2025

Uh oh!

mho22 commented Jul 23, 2025 •

edited

Loading

Uh oh!

mho22 commented Jul 23, 2025

Uh oh!

mho22 commented Jul 23, 2025

Uh oh!

adamziel commented Jul 23, 2025

Uh oh!

Uh oh!

Uh oh!

[ xdebug ] Bridge DBGP session with CDP server #2402

[ xdebug ] Bridge DBGP session with CDP server #2402

Uh oh!

Conversation

adamziel commented Jul 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation for the change, related issues

Related issues and pull requests

Implementation details

Testing Instructions

From Wordpress-Playground repository

From non-related Playground project

Uh oh!

mho22 commented Jul 22, 2025

Uh oh!

mho22 commented Jul 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mho22 commented Jul 23, 2025

Uh oh!

mho22 commented Jul 23, 2025

Uh oh!

adamziel commented Jul 23, 2025

Uh oh!

Uh oh!

Uh oh!

adamziel commented Jul 22, 2025 •

edited

Loading

mho22 commented Jul 23, 2025 •

edited

Loading