[ xdebug ] Add `--experimental-unsafe-ide-integration` option in Playground CLI #2777

mho22 · 2025-10-14T11:25:41Z

Motivation for the change, related issues

Based on issue #2763

The current pain we have when we run a Playground CLI command with Xdebug enabled is the absence of the files located in the VFS in our IDE.

This pull request gives visibility to the VFS files with the help of a .playground-xdebug-root symlink and the generation of path mappings inside the developer's IDE.

Only the mounts from inside the current working directory are mapped.

Implementation details

Symlinking > .playground-xdebug-root

It first removes a possibly existing symlink with name .playground-xdebug-root in the current working directory.
If --xdebug and --experimental-unsafe-ide-integration options are present, we symlink the temporary playground cli directory inside the current working directory.

Path mapping in IDEs

It first clears all the configs named WP Playground CLI - Listen for Xdebug in VSCode and PHPStorm config files.
If --xdebug and --experimental-unsafe-ide-integration options are present, we add IDE configs and path mappings in the related configs.
PHPStorm : it adds a new server with name WP Playground CLI - Listen for Xdebug in .idea/workspace.xml.
VSCode : it adds a new configuration with name WP Playground CLI - Listen for Xdebug in .vscode/launch.json.

Next steps are reported in the Xdebug Follow-up issue.

Testing Instructions (or ideally a Blueprint)

Run as follows:

node --no-warnings=ExperimentalWarning  --experimental-strip-types --experimental-transform-types --import ./pac
kages/meta/src/node-es-module-loader/register.mts ./packages/playground/cli/src/cli.ts server --xdebug --experimental-unsafe-ide-integration

adamziel · 2025-10-15T09:43:40Z

Let's support an optional explicit value, e.g. --experimental-ide=vscode just in case I work in multiple IDEs and only want to debug in one of them.

Also, this is the top of my vscode.json file:

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",

It means we cannot trivially use JSON.parse() :( These files are JSONC (JSON with comments) and we need a JSONC parser and serializer to work with them. Perhaps this one from Microsoft would work, maybe it's even the one used by VS Code.

packages/playground/cli/src/xdebug-path-mappings.ts

packages/playground/cli/src/run-cli.ts

…existent

adamziel · 2025-10-15T15:32:37Z

Some problems identifying the debug configuration:

Also, it's weird how the host is 127.0.0.1:9400 and port is 80.

packages/playground/cli/src/xdebug-path-mappings.ts

adamziel · 2025-10-15T15:39:11Z

XDebug is running even during the Blueprint execution – how cool! Also, that's likely only useful for code developers. Let's set some php.ini option to disable xdebug until WordPress fully boots.

adamziel · 2025-10-15T15:40:31Z

We're definitely getting there! 🎉

brandonpayton · 2025-10-18T18:24:42Z

I've been testing and reviewing the code and made some adjustments. The server host an port are now explicitly configured based on CLI's host and port.

I've seen PhpStorm report an Xdebug connection but haven't been able to hit any breakpoints yet.

brandonpayton · 2025-10-18T18:26:30Z

I've been testing with an auto-mounted WordPress dir nested under the Playground repo like:
~/src/playground/wp-plugin-test-wordpress% node --experimental-strip-types --experimental-transform-types --disable-warning=ExperimentalWarning --import ../packages/meta/src/node-es-module-loader/register.mts ../packages/playground/cli/src/cli.ts server --auto-mount=. --verbosity=debug --skip-wordpress-setup --xdebug --experimental-ide

brandonpayton · 2025-10-18T18:32:07Z

@adamziel is there any additional step in PhpStorm that I should have to do to tell PhpStorm to be able to hit breakpoints? Or should it just work if you have PhpStorm open and Playground CLI started with Xdebug support?

adamziel · 2025-10-18T21:49:48Z

I typically check "stop on first line" and set breakpoints from there @brandonpayton. And you need to turn on the "accept debug connections" toggle

adamziel · 2025-10-27T12:34:40Z

I've noticed this in my VS Code – might be related to something else, I'll need to dive into this. Also, I've added process.exit(1) on XDebug error to avoid silently passing failures and confusing users with "wait, why is my xdebug not connecting?". Also, JSONC.parse() needed the same options on re-validations so I added them. Will continue reviewing in 2 hours.

adamziel · 2025-10-27T14:53:10Z

Or in a few more hours, I forgot my power adapter :-)

adamziel · 2025-10-27T14:55:43Z

That error comes from xdebug, likely something wrong with our path mapping or the default initial breakpoint

https://bugs.xdebug.org/view.php?id=2302

mho22 · 2025-10-27T15:07:59Z

I found that github issue in VScode-php-debug :

xdebug/vscode-php-debug#1020

Maybe this could be related to your VSCode or an extension you added? Because I don't have any Unknown sourceReference 0 error displayed when running the command in the description inside the wordpress-playground directory.

brandonpayton · 2025-10-27T15:40:34Z

I plan to review in the next couple of hours. I also plan to make a few simple automated tests after factoring out IDE-specific bits into functions liks (pathMappings, inputConfigStr) => outputConfigStr, but those can come in a follow-up PR if needed.

adamziel · 2025-10-27T15:51:00Z

Yay! Also, when the ide integration is used, let's print something visible to tell the user what's next, e.g. per-IDE instructions, or a link to a new doc page explaining the next steps. Right now we know what to do, but it's not that obvious to a new person. Basically, let's handhold the user until they're in an active breakpoint cc @fellyph

brandonpayton · 2025-10-25T14:47:10Z

packages/playground/cli/src/xdebug-path-mappings.ts

+				// NOTE: PhpStorm quirk: Xdebug only works when the full URL (including port)
+				// is provided in `host`. The separate `port` field is ignored or misinterpreted,
+				// so we rely solely on host: "host:port".


Thanks for following upon on this!

brandonpayton · 2025-10-27T17:37:27Z

.vscode/launch.json

-          "PHP": "${input:phpVersion}"
-        },
-        "enableDWARF": true
-      },


The "Debug PHP-WASM" target may not be working well now, and the "Debug Playground CLI with DWARF symbols" is a bit clunky. But personally, I would like to leave at least the Playground CLI target in our launch.json because it gives me a starting point to customize and debug with DWARF symbols.

brandonpayton · 2025-10-27T17:41:01Z

packages/playground/cli/src/run-cli.ts

+					vfsPath: '/',
+				};
+
+				clearXdebugIDEConfig(IDEConfigName, process.cwd())


If we are going to exit if these operations fail, let's await here.

And if we await here we could switch back to try/catch blocks here if desired. It seems a bit strange to me to mix the await and the explicit promise-chaining styles, but I don't really think it matters either way.

brandonpayton · 2025-10-27T18:07:29Z

packages/playground/cli/src/xdebug-path-mappings.ts

+				xml ===
+				'<?xml version="1.0" encoding="UTF-8"?>\n<project version="4">\n	<component name="PhpServers">\n		<servers></servers>\n	</component>\n</project>'
+			) {
+				fs.unlinkSync(phpStormConfigFilePath);


Is there any harm in leaving the file in place? It doesn't seem safe to assume Playground CLI is the creator of the file.

I guess not, but I had in mind that if the remaining file looks like that, it certainly is because we created it in the first place. So we could destroy it. But I have the same feeling as you.

Cool. 👍 yeah, I bet it will be true in most cases that an empty config is one created by us, but we can't really prove it without some other evidence. It's possible a user had some other config and then removed it during debugging. (just talking this out, not trying to further explain 😄 )

brandonpayton · 2025-10-27T18:07:55Z

packages/playground/cli/src/xdebug-path-mappings.ts

+
+			const json = jsoncApplyEdits(content, edits);
+			if (json === '{\n    "configurations": []\n}') {
+				fs.unlinkSync(vsCodeConfigFilePath);


Same question as above. Should we just leave this file in place to be safe?

Sometimes vscode even auto adds sections to the file when opening various kinds of files?

If vscode or phpstorm auto adds sections to the file, this means the file won't have that structure anymore so we won't have to destroy it. But, I still have the same feeling as you.

adamziel · 2025-10-28T00:10:14Z

packages/php-wasm/node/src/lib/xdebug/with-xdebug.ts

 					'/internal/shared/extensions/xdebug.ini'
 				)
 			) {
+				const ideKey = xdebugOptions?.ideKey || 'PLAYGROUNDCLI';


PHPStorm seems to require the IDE key for debug configuration

adamziel · 2025-10-28T00:12:33Z

I've added some developer instructions:

Also:

Creating a new debug configuration in PHPStorm config
Factored the config-altering logic and added test coverage

brandonpayton · 2025-10-28T00:45:40Z

Thanks for adding tests, @adamziel! I ended up getting pulled away, was going to write them now, and found there was a conflict with the existing test file. Cool! Will read and see if there is anything to add.

brandonpayton · 2025-10-28T02:46:37Z

@adamziel and @mho22, thank you for getting this ready today. It looks like this is about ready for merge.

I made a couple of minor fixes:

Fix xdebug ini test that didn't acknowledge new ideKey config
Move clearXdebugIDEConfig() into the run-cli try/catch because that operation can also throw.

If the tests pass, I think this is ready to merge.

brandonpayton · 2025-10-28T03:25:37Z

.vscode/launch.json

+      "runtimeArgs": [
+        "--inspect-brk",
+        "--loader=${workspaceFolder}/packages/nx-extensions/src/executors/built-script/loader.mjs"
+      ]


NOTE: While restoring the removed launch targets, I ended up formatting the file, so there are some whitespace changes like this.

brandonpayton

I think this is good to go. Thanks, everyone!

brandonpayton · 2025-10-28T03:55:21Z

I'll go ahead and merge this since I'm not aware of any remaining reservations. As a follow-up, I plan to submit a PR to have an initial worker for boot that does not hit Xdebug breakpoints during boot (unless maybe an additional flag is passed). I started this locally but don't remember how far along it is. Will see tomorrow.

mho22 · 2025-10-28T06:48:47Z

🎉 🎉 🎉 ! Thank you @brandonpayton and @adamziel ! What a teamwork !

brandonpayton · 2025-10-28T13:27:15Z

🎉 🎉 🎉 ! Thank you @brandonpayton and @adamziel ! What a teamwork !

Thank you, @mho22! This was fun!

@fellyph

…wasm CLI (#2947) ## Motivation for the change, related issues Based on issue #2763 and following pull request #2777 This pull request generates the IDE configuration files inside the developer's IDE. ## Implementation details - It first clears all the configs named `PHP.wasm CLI - Listen for Xdebug` in VSCode and PHPStorm config files. - If `--xdebug` and `--experimental-unsafe-ide-integration` options are present, we add IDE configs in the related configs. - PHPStorm : it adds a new `server` with name `PHP.wasm CLI - Listen for Xdebug` in `.idea/workspace.xml`. - VSCode : it adds a new `configuration` with name `PHP.wasm CLI - Listen for Xdebug` in `.vscode/launch.json`. - Correction of an error in Playground CLI console.logs. - Creation of a new distinct package named `@php-wasm/cli-util` which is integrated into PHP.wasm CLI and Playground CLI with the `xdebug-path-mappings`. Next steps are reported in the [Xdebug Follow-up issue](#2315). ## Testing Instructions (or ideally a Blueprint) CI 🧪 test-php-wasm-cli-util cc @fellyph

Add Xdebug path mappings when --experimental-ide option enabled

ce85c95

mho22 changed the title ~~[ xdebug ] Add --experimental-ide option to set xdebug path mappings~~ [ xdebug ] Add --experimental-ide option in Playground CLI Oct 14, 2025

mho22 mentioned this pull request Oct 14, 2025

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

Open

11 tasks

mho22 added [Type] Enhancement New feature or request [Package][@wp-playground] CLI XDebug labels Oct 14, 2025

mho22 added 2 commits October 14, 2025 18:15

Implement IDE config addition and removal

fd9ab80

Add try catch around JSON.parse

66c8620