Skip to content

Commit a875920

Browse files
adamzielmho22
adamziel
and
mho22
authored
[ 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]>
1 parent 494a814 commit a875920

20 files changed

+1428
-509
lines changed

‎CHANGELOG.md‎

Lines changed: 15 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -4,61 +4,59 @@ All notable changes to this project are documented in this file by a CI job
44
that runs on every NPM release. The file follows the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
55
format.
66

7-
## [v2.0.1] (2025-07-23)
7+
## [v2.0.1] (2025-07-23)
88

99
### Blueprints
1010

11-
- Rewrite paths in the wp-cli step. Improve error reporting. ([#2406](https://github.com/WordPress/wordpress-playground/pull/2406))
11+
- Rewrite paths in the wp-cli step. Improve error reporting. ([#2406](https://github.com/WordPress/wordpress-playground/pull/2406))
1212

1313
### Contributors
1414

1515
The following contributors merged PRs in this release:
1616

1717
@adamziel
1818

19-
20-
## [v2.0.0] (2025-07-23)
19+
## [v2.0.0] (2025-07-23)
2120

2221
### Enhancements
2322

24-
- [Playground CLI] Improve error reporting. ([#2401](https://github.com/WordPress/wordpress-playground/pull/2401))
25-
- [Playground CLI] Kebab-case yargs options declarations. ([#2399](https://github.com/WordPress/wordpress-playground/pull/2399))
23+
- [Playground CLI] Improve error reporting. ([#2401](https://github.com/WordPress/wordpress-playground/pull/2401))
24+
- [Playground CLI] Kebab-case yargs options declarations. ([#2399](https://github.com/WordPress/wordpress-playground/pull/2399))
2625

2726
### Blueprints
2827

29-
- Expose Blueprints v2 runner in Playground CLI. ([#2394](https://github.com/WordPress/wordpress-playground/pull/2394))
30-
- Extract Blueprint v1-specific parts of Playground CLI. ([#2392](https://github.com/WordPress/wordpress-playground/pull/2392))
31-
- [Playground CLI] Separate Blueprints v1 and Blueprints v2 code paths. ([#2396](https://github.com/WordPress/wordpress-playground/pull/2396))
28+
- Expose Blueprints v2 runner in Playground CLI. ([#2394](https://github.com/WordPress/wordpress-playground/pull/2394))
29+
- Extract Blueprint v1-specific parts of Playground CLI. ([#2392](https://github.com/WordPress/wordpress-playground/pull/2392))
30+
- [Playground CLI] Separate Blueprints v1 and Blueprints v2 code paths. ([#2396](https://github.com/WordPress/wordpress-playground/pull/2396))
3231

3332
### Tools
3433

35-
- [XDebug] Add a mock @php-wasm/xdebug-bridge package. ([#2398](https://github.com/WordPress/wordpress-playground/pull/2398))
34+
- [XDebug] Add a mock @php-wasm/xdebug-bridge package. ([#2398](https://github.com/WordPress/wordpress-playground/pull/2398))
3635

3736
### Documentation
3837

39-
- Adding Brazilian Portuguese translation for developer documentation. ([#2391](https://github.com/WordPress/wordpress-playground/pull/2391))
38+
- Adding Brazilian Portuguese translation for developer documentation. ([#2391](https://github.com/WordPress/wordpress-playground/pull/2391))
4039

4140
### Website
4241

43-
- [Remote] Use CORS proxy in embedded Playgrounds. ([#2369](https://github.com/WordPress/wordpress-playground/pull/2369))
42+
- [Remote] Use CORS proxy in embedded Playgrounds. ([#2369](https://github.com/WordPress/wordpress-playground/pull/2369))
4443

4544
### Bug Fixes
4645

47-
- CLI: Fix --login option and "landingPage" Blueprint property. ([#2344](https://github.com/WordPress/wordpress-playground/pull/2344))
46+
- CLI: Fix --login option and "landingPage" Blueprint property. ([#2344](https://github.com/WordPress/wordpress-playground/pull/2344))
4847

4948
### Various
5049

51-
- Add Japanese translations to steps and steps shorthands. ([#2386](https://github.com/WordPress/wordpress-playground/pull/2386))
52-
- Add OPCache support. ([#2400](https://github.com/WordPress/wordpress-playground/pull/2400))
53-
- [Node] Gracefully handle connection errors in the outbound network proxy. ([#2370](https://github.com/WordPress/wordpress-playground/pull/2370))
50+
- Add Japanese translations to steps and steps shorthands. ([#2386](https://github.com/WordPress/wordpress-playground/pull/2386))
51+
- Add OPCache support. ([#2400](https://github.com/WordPress/wordpress-playground/pull/2400))
52+
- [Node] Gracefully handle connection errors in the outbound network proxy. ([#2370](https://github.com/WordPress/wordpress-playground/pull/2370))
5453

5554
### Contributors
5655

5756
The following contributors merged PRs in this release:
5857

5958
@adamziel @fellyph @shimotmk @zaerl
6059

61-
6260
## [v1.2.3] (2025-07-21)
6361

6462
### Enhancements

‎package-lock.json‎

Lines changed: 33 additions & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,7 @@
6767
"dependencies": {
6868
"@preact/signals-react": "1.3.6",
6969
"@reduxjs/toolkit": "2.6.1",
70+
"@types/xml2js": "0.4.14",
7071
"@wordpress/dataviews": "4.5.0",
7172
"@zip.js/zip.js": "2.7.57",
7273
"ajv": "8.12.0",
@@ -87,6 +88,7 @@
8788
"react-transition-group": "4.4.5",
8889
"sha.js": "2.4.11",
8990
"wasm-feature-detect": "1.8.0",
91+
"xml2js": "0.6.2",
9092
"yargs": "17.7.2"
9193
},
9294
"devDependencies": {

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

Lines changed: 15 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -9,61 +9,59 @@ All notable changes to this project are documented in this file by a CI job
99
that runs on every NPM release. The file follows the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
1010
format.
1111

12-
## [v2.0.1] (2025-07-23)
12+
## [v2.0.1] (2025-07-23)
1313

1414
### Blueprints
1515

16-
- Rewrite paths in the wp-cli step. Improve error reporting. ([#2406](https://github.com/WordPress/wordpress-playground/pull/2406))
16+
- Rewrite paths in the wp-cli step. Improve error reporting. ([#2406](https://github.com/WordPress/wordpress-playground/pull/2406))
1717

1818
### Contributors
1919

2020
The following contributors merged PRs in this release:
2121

2222
@adamziel
2323

24-
25-
## [v2.0.0] (2025-07-23)
24+
## [v2.0.0] (2025-07-23)
2625

2726
### Enhancements
2827

29-
- [Playground CLI] Improve error reporting. ([#2401](https://github.com/WordPress/wordpress-playground/pull/2401))
30-
- [Playground CLI] Kebab-case yargs options declarations. ([#2399](https://github.com/WordPress/wordpress-playground/pull/2399))
28+
- [Playground CLI] Improve error reporting. ([#2401](https://github.com/WordPress/wordpress-playground/pull/2401))
29+
- [Playground CLI] Kebab-case yargs options declarations. ([#2399](https://github.com/WordPress/wordpress-playground/pull/2399))
3130

3231
### Blueprints
3332

34-
- Expose Blueprints v2 runner in Playground CLI. ([#2394](https://github.com/WordPress/wordpress-playground/pull/2394))
35-
- Extract Blueprint v1-specific parts of Playground CLI. ([#2392](https://github.com/WordPress/wordpress-playground/pull/2392))
36-
- [Playground CLI] Separate Blueprints v1 and Blueprints v2 code paths. ([#2396](https://github.com/WordPress/wordpress-playground/pull/2396))
33+
- Expose Blueprints v2 runner in Playground CLI. ([#2394](https://github.com/WordPress/wordpress-playground/pull/2394))
34+
- Extract Blueprint v1-specific parts of Playground CLI. ([#2392](https://github.com/WordPress/wordpress-playground/pull/2392))
35+
- [Playground CLI] Separate Blueprints v1 and Blueprints v2 code paths. ([#2396](https://github.com/WordPress/wordpress-playground/pull/2396))
3736

3837
### Tools
3938

40-
- [XDebug] Add a mock @php-wasm/xdebug-bridge package. ([#2398](https://github.com/WordPress/wordpress-playground/pull/2398))
39+
- [XDebug] Add a mock @php-wasm/xdebug-bridge package. ([#2398](https://github.com/WordPress/wordpress-playground/pull/2398))
4140

4241
### Documentation
4342

44-
- Adding Brazilian Portuguese translation for developer documentation. ([#2391](https://github.com/WordPress/wordpress-playground/pull/2391))
43+
- Adding Brazilian Portuguese translation for developer documentation. ([#2391](https://github.com/WordPress/wordpress-playground/pull/2391))
4544

4645
### Website
4746

48-
- [Remote] Use CORS proxy in embedded Playgrounds. ([#2369](https://github.com/WordPress/wordpress-playground/pull/2369))
47+
- [Remote] Use CORS proxy in embedded Playgrounds. ([#2369](https://github.com/WordPress/wordpress-playground/pull/2369))
4948

5049
### Bug Fixes
5150

52-
- CLI: Fix --login option and "landingPage" Blueprint property. ([#2344](https://github.com/WordPress/wordpress-playground/pull/2344))
51+
- CLI: Fix --login option and "landingPage" Blueprint property. ([#2344](https://github.com/WordPress/wordpress-playground/pull/2344))
5352

5453
### Various
5554

56-
- Add Japanese translations to steps and steps shorthands. ([#2386](https://github.com/WordPress/wordpress-playground/pull/2386))
57-
- Add OPCache support. ([#2400](https://github.com/WordPress/wordpress-playground/pull/2400))
58-
- [Node] Gracefully handle connection errors in the outbound network proxy. ([#2370](https://github.com/WordPress/wordpress-playground/pull/2370))
55+
- Add Japanese translations to steps and steps shorthands. ([#2386](https://github.com/WordPress/wordpress-playground/pull/2386))
56+
- Add OPCache support. ([#2400](https://github.com/WordPress/wordpress-playground/pull/2400))
57+
- [Node] Gracefully handle connection errors in the outbound network proxy. ([#2370](https://github.com/WordPress/wordpress-playground/pull/2370))
5958

6059
### Contributors
6160

6261
The following contributors merged PRs in this release:
6362

6463
@adamziel @fellyph @shimotmk @zaerl
6564

66-
6765
## [v1.2.3] (2025-07-21)
6866

6967
### Enhancements

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,9 @@
88
},
99
{
1010
"files": ["*.ts", "*.tsx"],
11-
"rules": {}
11+
"rules": {
12+
"no-console": 0
13+
}
1214
},
1315
{
1416
"files": ["*.js", "*.jsx"],

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

Lines changed: 25 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -13,24 +13,21 @@ npm install @php-wasm/xdebug-bridge
1313
### Programmatic API
1414

1515
```typescript
16-
import { startXDebugBridge } from '@php-wasm/xdebug-bridge';
16+
import { startBridge } from './xdebug-bridge/src/start-bridge';
1717

1818
// Start with default settings
19-
const server = startXDebugBridge();
19+
const server = startBridge();
2020
await server.start();
2121

2222
// Start with custom configuration
23-
const server = startXDebugBridge({
24-
protocol: 'cdp', // or 'dap'
25-
xdebugServerPort: 9003, // XDebug connection port
26-
xdebugServerHost: 'localhost',
27-
verbose: false, // Silent mode
23+
const server = startBridge({
24+
cdpHost: 'localhost', // CDP connection host
25+
cdpPort: 9229, // CDP connection port
26+
dbgpPort: 9003, // XDebug connection port
27+
phpRoot: './', // Root to directory
2828
});
2929

3030
await server.start();
31-
32-
// Stop the server
33-
await server.stop();
3431
```
3532

3633
### CLI Usage
@@ -42,29 +39,31 @@ npx xdebug-bridge
4239
# Custom port and verbose logging
4340
npx xdebug-bridge --port 9000 --verbose
4441

45-
# DAP protocol, bind to all interfaces
46-
npx xdebug-bridge --protocol dap --host 0.0.0.0
47-
4842
# Show help
4943
npx xdebug-bridge --help
5044
```
5145

5246
## Configuration Options
5347

54-
- `protocol`: Protocol to use ('cdp' or 'dap', default: 'cdp')
55-
- `xdebugServerPort`: Port to listen for XDebug connections (default: 9003)
56-
- `xdebugServerHost`: Host to bind to (default: 'localhost')
57-
- `verbose`: Enable verbose logging (default: false for API, true for CLI)
58-
- `logger`: Custom logger function
48+
- `cdpPort`: Port to listen for CDP connections (default: 9229)
49+
- `cdpHost`: Host to bind to (default: 'localhost')
50+
- `dbgpPort`: Port to listen for XDebug connections (default: 9003)
51+
- `phpRoot`: Root path for php files;
52+
- `remoteRoot`: Remote root path for php files;
53+
- `localRoot`: Local root path for php files;
54+
- `phpInstance`: PHP instance
55+
- `getPHPFile`: Custom file listing function
5956

6057
## Events
6158

62-
The server emits events for monitoring connection activity:
59+
The bridge listens to events for monitoring connection activity:
60+
61+
- `connected`: Xdebug Server has started
62+
- `close`: Xdebug Server has stopped
63+
- `message`: Raw XDebug data received
64+
- `error`: Xdebug Server error occurred
6365

64-
- `started`: Server has started
65-
- `stopped`: Server has stopped
66-
- `connection`: New XDebug connection established
67-
- `disconnection`: XDebug connection closed
68-
- `xdebugData`: Raw XDebug data received
69-
- `error`: Server error occurred
70-
- `socketError`: Socket-level error occurred
66+
- `clientConnected`: Devtools client connected
67+
- `clientDisconnected`: Devtools client disconnected
68+
- `message`: Raw Devtools data received
69+
- `error`: Devtools client error occurred

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@
2626
"type": "module",
2727
"main": "./index.cjs",
2828
"module": "./index.js",
29-
"bin": "cli.js",
29+
"bin": "xdebug-bridge.js",
3030
"typedoc": {
3131
"entryPoint": "./src/index.ts",
3232
"readmeFile": "./README.md",

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

Lines changed: 21 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@
2929
"executor": "@nx/vite:build",
3030
"outputs": ["{options.outputPath}"],
3131
"options": {
32-
"main": "dist/packages/php-wasm/xdebug-bridge/index.js",
32+
"main": "dist/packages/php-wasm/xdebug-bridge/src/cli.js",
3333
"outputPath": "dist/packages/php-wasm/xdebug-bridge"
3434
},
3535
"defaultConfiguration": "production",
@@ -45,27 +45,40 @@
4545
"dev": {
4646
"executor": "nx:run-commands",
4747
"options": {
48-
"command": "bun --watch ./packages/php-wasm/xdebug-bridge/src/cli.ts",
48+
"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",
4949
"tty": true
5050
}
5151
},
52+
"lint": {
53+
"executor": "@nx/eslint:lint",
54+
"outputs": ["{options.outputFile}"],
55+
"options": {
56+
"lintFilePatterns": ["packages/php-wasm/xdebug-bridge/**/*.ts"]
57+
}
58+
},
59+
"package-for-self-hosting": {
60+
"executor": "@wp-playground/nx-extensions:package-for-self-hosting",
61+
"dependsOn": ["build"]
62+
},
5263
"test": {
5364
"executor": "@nx/vite:test",
5465
"outputs": [
5566
"{workspaceRoot}/coverage/packages/php-wasm/xdebug-bridge"
5667
],
5768
"options": {
5869
"reportsDirectory": "../../../coverage/packages/php-wasm/xdebug-bridge",
59-
"testFiles": ["tests/mock-test.spec.ts"]
70+
"testFiles": ["mock-test.spec.ts"]
6071
}
6172
},
62-
"lint": {
63-
"executor": "@nx/eslint:lint",
64-
"outputs": ["{options.outputFile}"],
73+
"typecheck": {
74+
"executor": "nx:run-commands",
6575
"options": {
66-
"lintFilePatterns": ["packages/php-wasm/xdebug-bridge/**/*.ts"]
76+
"commands": [
77+
"tsc -p packages/php-wasm/xdebug-bridge/tsconfig.lib.json --noEmit",
78+
"tsc -p packages/php-wasm/xdebug-bridge/tsconfig.spec.json --noEmit"
79+
]
6780
}
6881
}
6982
},
70-
"tags": ["php-wasm"]
83+
"tags": ["scope:php-binaries"]
7184
}

‎packages/php-wasm/xdebug-bridge/public/xdebug-bridge.js‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
#!/usr/bin/env node
2+
import './cli.js';

0 commit comments

Comments
 (0)