[ xdebug ] Bridge DBGP session with CDP server (#2402)

## Motivation for the change, related issues

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

[Roadmap](#2315)

## Related issues and pull requests

- #2346
- #2398
- #2288

## 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
<?php

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

echo "Output!\n";

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

test();
```

### From Wordpress-Playground repository

1. 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...
```

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

1. Install dependencies

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

2. 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...
```

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

```
> npx cli --xdebug xdebug.php

Output!
Hello Xdebug World!
```

<img width="748" height="409" alt="screencapture"
src="https://github.com/user-attachments/assets/b0232831-c9b3-4bb2-95aa-b1d51b72766e"
/>

---------

Co-authored-by: mho22 <[email protected]>

Author: adamziel

CHANGELOG.md

@@ -4,61 +4,59 @@ All notable changes to this project are documented in this file by a CI job
 that runs on every NPM release. The file follows the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 format.
 
-## [v2.0.1] (2025-07-23) 
+## [v2.0.1] (2025-07-23)
 
 ### Blueprints
 
-- Rewrite paths in the wp-cli step. Improve error reporting. ([#2406](https://github.com/WordPress/wordpress-playground/pull/2406))
+-   Rewrite paths in the wp-cli step. Improve error reporting. ([#2406](https://github.com/WordPress/wordpress-playground/pull/2406))
 
 ### Contributors
 
 The following contributors merged PRs in this release:
 
 @adamziel
 
-
-## [v2.0.0] (2025-07-23) 
+## [v2.0.0] (2025-07-23)
 
 ### Enhancements
 
-- [Playground CLI] Improve error reporting. ([#2401](https://github.com/WordPress/wordpress-playground/pull/2401))
-- [Playground CLI] Kebab-case yargs options declarations. ([#2399](https://github.com/WordPress/wordpress-playground/pull/2399))
+-   [Playground CLI] Improve error reporting. ([#2401](https://github.com/WordPress/wordpress-playground/pull/2401))
+-   [Playground CLI] Kebab-case yargs options declarations. ([#2399](https://github.com/WordPress/wordpress-playground/pull/2399))
 
 ### Blueprints
 
-- Expose Blueprints v2 runner in Playground CLI. ([#2394](https://github.com/WordPress/wordpress-playground/pull/2394))
-- Extract Blueprint v1-specific parts of Playground CLI. ([#2392](https://github.com/WordPress/wordpress-playground/pull/2392))
-- [Playground CLI] Separate Blueprints v1 and Blueprints v2 code paths. ([#2396](https://github.com/WordPress/wordpress-playground/pull/2396))
+-   Expose Blueprints v2 runner in Playground CLI. ([#2394](https://github.com/WordPress/wordpress-playground/pull/2394))
+-   Extract Blueprint v1-specific parts of Playground CLI. ([#2392](https://github.com/WordPress/wordpress-playground/pull/2392))
+-   [Playground CLI] Separate Blueprints v1 and Blueprints v2 code paths. ([#2396](https://github.com/WordPress/wordpress-playground/pull/2396))
 
 ### Tools
 
-- [XDebug] Add a mock @php-wasm/xdebug-bridge package. ([#2398](https://github.com/WordPress/wordpress-playground/pull/2398))
+-   [XDebug] Add a mock @php-wasm/xdebug-bridge package. ([#2398](https://github.com/WordPress/wordpress-playground/pull/2398))
 
 ### Documentation
 
-- Adding Brazilian Portuguese translation for developer documentation. ([#2391](https://github.com/WordPress/wordpress-playground/pull/2391))
+-   Adding Brazilian Portuguese translation for developer documentation. ([#2391](https://github.com/WordPress/wordpress-playground/pull/2391))
 
 ### Website
 
-- [Remote] Use CORS proxy in embedded Playgrounds. ([#2369](https://github.com/WordPress/wordpress-playground/pull/2369))
+-   [Remote] Use CORS proxy in embedded Playgrounds. ([#2369](https://github.com/WordPress/wordpress-playground/pull/2369))
 
 ### Bug Fixes
 
-- CLI: Fix --login option and "landingPage" Blueprint property. ([#2344](https://github.com/WordPress/wordpress-playground/pull/2344))
+-   CLI: Fix --login option and "landingPage" Blueprint property. ([#2344](https://github.com/WordPress/wordpress-playground/pull/2344))
 
 ### Various
 
-- Add Japanese translations to steps and steps shorthands. ([#2386](https://github.com/WordPress/wordpress-playground/pull/2386))
-- Add OPCache support. ([#2400](https://github.com/WordPress/wordpress-playground/pull/2400))
-- [Node] Gracefully handle connection errors in the outbound network proxy. ([#2370](https://github.com/WordPress/wordpress-playground/pull/2370))
+-   Add Japanese translations to steps and steps shorthands. ([#2386](https://github.com/WordPress/wordpress-playground/pull/2386))
+-   Add OPCache support. ([#2400](https://github.com/WordPress/wordpress-playground/pull/2400))
+-   [Node] Gracefully handle connection errors in the outbound network proxy. ([#2370](https://github.com/WordPress/wordpress-playground/pull/2370))
 
 ### Contributors
 
 The following contributors merged PRs in this release:
 
 @adamziel @fellyph @shimotmk @zaerl
 
-
 ## [v1.2.3] (2025-07-21)
 
 ### Enhancements

package-lock.json

@@ -67,6 +67,7 @@
 	"dependencies": {
 		"@preact/signals-react": "1.3.6",
 		"@reduxjs/toolkit": "2.6.1",
+		"@types/xml2js": "0.4.14",
 		"@wordpress/dataviews": "4.5.0",
 		"@zip.js/zip.js": "2.7.57",
 		"ajv": "8.12.0",
@@ -87,6 +88,7 @@
 		"react-transition-group": "4.4.5",
 		"sha.js": "2.4.11",
 		"wasm-feature-detect": "1.8.0",
+		"xml2js": "0.6.2",
 		"yargs": "17.7.2"
 	},
 	"devDependencies": {

package.json

@@ -9,61 +9,59 @@ All notable changes to this project are documented in this file by a CI job
 that runs on every NPM release. The file follows the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 format.
 
-## [v2.0.1] (2025-07-23) 
+## [v2.0.1] (2025-07-23)
 
 ### Blueprints
 
-- Rewrite paths in the wp-cli step. Improve error reporting. ([#2406](https://github.com/WordPress/wordpress-playground/pull/2406))
+-   Rewrite paths in the wp-cli step. Improve error reporting. ([#2406](https://github.com/WordPress/wordpress-playground/pull/2406))
 
 ### Contributors
 
 The following contributors merged PRs in this release:
 
 @adamziel
 
-
-## [v2.0.0] (2025-07-23) 
+## [v2.0.0] (2025-07-23)
 
 ### Enhancements
 
-- [Playground CLI] Improve error reporting. ([#2401](https://github.com/WordPress/wordpress-playground/pull/2401))
-- [Playground CLI] Kebab-case yargs options declarations. ([#2399](https://github.com/WordPress/wordpress-playground/pull/2399))
+-   [Playground CLI] Improve error reporting. ([#2401](https://github.com/WordPress/wordpress-playground/pull/2401))
+-   [Playground CLI] Kebab-case yargs options declarations. ([#2399](https://github.com/WordPress/wordpress-playground/pull/2399))
 
 ### Blueprints
 
-- Expose Blueprints v2 runner in Playground CLI. ([#2394](https://github.com/WordPress/wordpress-playground/pull/2394))
-- Extract Blueprint v1-specific parts of Playground CLI. ([#2392](https://github.com/WordPress/wordpress-playground/pull/2392))
-- [Playground CLI] Separate Blueprints v1 and Blueprints v2 code paths. ([#2396](https://github.com/WordPress/wordpress-playground/pull/2396))
+-   Expose Blueprints v2 runner in Playground CLI. ([#2394](https://github.com/WordPress/wordpress-playground/pull/2394))
+-   Extract Blueprint v1-specific parts of Playground CLI. ([#2392](https://github.com/WordPress/wordpress-playground/pull/2392))
+-   [Playground CLI] Separate Blueprints v1 and Blueprints v2 code paths. ([#2396](https://github.com/WordPress/wordpress-playground/pull/2396))
 
 ### Tools
 
-- [XDebug] Add a mock @php-wasm/xdebug-bridge package. ([#2398](https://github.com/WordPress/wordpress-playground/pull/2398))
+-   [XDebug] Add a mock @php-wasm/xdebug-bridge package. ([#2398](https://github.com/WordPress/wordpress-playground/pull/2398))
 
 ### Documentation
 
-- Adding Brazilian Portuguese translation for developer documentation. ([#2391](https://github.com/WordPress/wordpress-playground/pull/2391))
+-   Adding Brazilian Portuguese translation for developer documentation. ([#2391](https://github.com/WordPress/wordpress-playground/pull/2391))
 
 ### Website
 
-- [Remote] Use CORS proxy in embedded Playgrounds. ([#2369](https://github.com/WordPress/wordpress-playground/pull/2369))
+-   [Remote] Use CORS proxy in embedded Playgrounds. ([#2369](https://github.com/WordPress/wordpress-playground/pull/2369))
 
 ### Bug Fixes
 
-- CLI: Fix --login option and "landingPage" Blueprint property. ([#2344](https://github.com/WordPress/wordpress-playground/pull/2344))
+-   CLI: Fix --login option and "landingPage" Blueprint property. ([#2344](https://github.com/WordPress/wordpress-playground/pull/2344))
 
 ### Various
 
-- Add Japanese translations to steps and steps shorthands. ([#2386](https://github.com/WordPress/wordpress-playground/pull/2386))
-- Add OPCache support. ([#2400](https://github.com/WordPress/wordpress-playground/pull/2400))
-- [Node] Gracefully handle connection errors in the outbound network proxy. ([#2370](https://github.com/WordPress/wordpress-playground/pull/2370))
+-   Add Japanese translations to steps and steps shorthands. ([#2386](https://github.com/WordPress/wordpress-playground/pull/2386))
+-   Add OPCache support. ([#2400](https://github.com/WordPress/wordpress-playground/pull/2400))
+-   [Node] Gracefully handle connection errors in the outbound network proxy. ([#2370](https://github.com/WordPress/wordpress-playground/pull/2370))
 
 ### Contributors
 
 The following contributors merged PRs in this release:
 
 @adamziel @fellyph @shimotmk @zaerl
 
-
 ## [v1.2.3] (2025-07-21)
 
 ### Enhancements

packages/docs/site/docs/main/changelog.md

@@ -8,7 +8,9 @@
 		},
 		{
 			"files": ["*.ts", "*.tsx"],
-			"rules": {}
+			"rules": {
+				"no-console": 0
+			}
 		},
 		{
 			"files": ["*.js", "*.jsx"],

packages/php-wasm/xdebug-bridge/.eslintrc.json

@@ -13,24 +13,21 @@ npm install @php-wasm/xdebug-bridge
 ### Programmatic API
 
 ```typescript
-import { startXDebugBridge } from '@php-wasm/xdebug-bridge';
+import { startBridge } from './xdebug-bridge/src/start-bridge';
 
 // Start with default settings
-const server = startXDebugBridge();
+const server = startBridge();
 await server.start();
 
 // Start with custom configuration
-const server = startXDebugBridge({
-	protocol: 'cdp', // or 'dap'
-	xdebugServerPort: 9003, // XDebug connection port
-	xdebugServerHost: 'localhost',
-	verbose: false, // Silent mode
+const server = startBridge({
+	cdpHost: 'localhost', // CDP connection host
+	cdpPort: 9229, // CDP connection port
+	dbgpPort: 9003, // XDebug connection port
+	phpRoot: './', // Root to directory
 });
 
 await server.start();
-
-// Stop the server
-await server.stop();
 ```
 
 ### CLI Usage
@@ -42,29 +39,31 @@ npx xdebug-bridge
 # Custom port and verbose logging
 npx xdebug-bridge --port 9000 --verbose
 
-# DAP protocol, bind to all interfaces
-npx xdebug-bridge --protocol dap --host 0.0.0.0
-
 # Show help
 npx xdebug-bridge --help
 ```
 
 ## Configuration Options
 
--   `protocol`: Protocol to use ('cdp' or 'dap', default: 'cdp')
--   `xdebugServerPort`: Port to listen for XDebug connections (default: 9003)
--   `xdebugServerHost`: Host to bind to (default: 'localhost')
--   `verbose`: Enable verbose logging (default: false for API, true for CLI)
--   `logger`: Custom logger function
+-   `cdpPort`: Port to listen for CDP connections (default: 9229)
+-   `cdpHost`: Host to bind to (default: 'localhost')
+-   `dbgpPort`: Port to listen for XDebug connections (default: 9003)
+-   `phpRoot`: Root path for php files;
+-   `remoteRoot`: Remote root path for php files;
+-   `localRoot`: Local root path for php files;
+-   `phpInstance`: PHP instance
+-   `getPHPFile`: Custom file listing function
 
 ## Events
 
-The server emits events for monitoring connection activity:
+The bridge listens to events for monitoring connection activity:
+
+-   `connected`: Xdebug Server has started
+-   `close`: Xdebug Server has stopped
+-   `message`: Raw XDebug data received
+-   `error`: Xdebug Server error occurred
 
--   `started`: Server has started
--   `stopped`: Server has stopped
--   `connection`: New XDebug connection established
--   `disconnection`: XDebug connection closed
--   `xdebugData`: Raw XDebug data received
--   `error`: Server error occurred
--   `socketError`: Socket-level error occurred
+-   `clientConnected`: Devtools client connected
+-   `clientDisconnected`: Devtools client disconnected
+-   `message`: Raw Devtools data received
+-   `error`: Devtools client error occurred

packages/php-wasm/xdebug-bridge/README.md

@@ -26,7 +26,7 @@
 	"type": "module",
 	"main": "./index.cjs",
 	"module": "./index.js",
-	"bin": "cli.js",
+	"bin": "xdebug-bridge.js",
 	"typedoc": {
 		"entryPoint": "./src/index.ts",
 		"readmeFile": "./README.md",

packages/php-wasm/xdebug-bridge/package.json

@@ -29,7 +29,7 @@
 			"executor": "@nx/vite:build",
 			"outputs": ["{options.outputPath}"],
 			"options": {
-				"main": "dist/packages/php-wasm/xdebug-bridge/index.js",
+				"main": "dist/packages/php-wasm/xdebug-bridge/src/cli.js",
 				"outputPath": "dist/packages/php-wasm/xdebug-bridge"
 			},
 			"defaultConfiguration": "production",
@@ -45,27 +45,40 @@
 		"dev": {
 			"executor": "nx:run-commands",
 			"options": {
-				"command": "bun --watch ./packages/php-wasm/xdebug-bridge/src/cli.ts",
+				"command": "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/cli.ts",
 				"tty": true
 			}
 		},
+		"lint": {
+			"executor": "@nx/eslint:lint",
+			"outputs": ["{options.outputFile}"],
+			"options": {
+				"lintFilePatterns": ["packages/php-wasm/xdebug-bridge/**/*.ts"]
+			}
+		},
+		"package-for-self-hosting": {
+			"executor": "@wp-playground/nx-extensions:package-for-self-hosting",
+			"dependsOn": ["build"]
+		},
 		"test": {
 			"executor": "@nx/vite:test",
 			"outputs": [
 				"{workspaceRoot}/coverage/packages/php-wasm/xdebug-bridge"
 			],
 			"options": {
 				"reportsDirectory": "../../../coverage/packages/php-wasm/xdebug-bridge",
-				"testFiles": ["tests/mock-test.spec.ts"]
+				"testFiles": ["mock-test.spec.ts"]
 			}
 		},
-		"lint": {
-			"executor": "@nx/eslint:lint",
-			"outputs": ["{options.outputFile}"],
+		"typecheck": {
+			"executor": "nx:run-commands",
 			"options": {
-				"lintFilePatterns": ["packages/php-wasm/xdebug-bridge/**/*.ts"]
+				"commands": [
+					"tsc -p packages/php-wasm/xdebug-bridge/tsconfig.lib.json --noEmit",
+					"tsc -p packages/php-wasm/xdebug-bridge/tsconfig.spec.json --noEmit"
+				]
 			}
 		}
 	},
-	"tags": ["php-wasm"]
+	"tags": ["scope:php-binaries"]
 }

packages/php-wasm/xdebug-bridge/project.json

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import './cli.js';