[ xdebug ] Add `--experimental-ide` 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 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

It first removes a possibly existing symlink with name .playground in the current working directory.
If --xdebug and --experimental-ide 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-ide 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.

Testing Instructions (or ideally a Blueprint)

CI

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.

adamziel · 2025-10-15T09:59:48Z

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

+		try {
+			config = JSON.parse(fs.readFileSync(configFilePath, 'utf-8'));
+		} catch {
+			logger.warn(


This is a big deal, let's display it in red and kill the process at this point. Otherwise, when things don't work, the user will scratch their head and think "oh that option doesn't work?"

I used jsonc-parser as suggested in your comment, and it became easier to manipulate JSON.

Now I parse the file and if it finds errors, it logs an error and exits with process.exit(1).

My question is, should I use the process.exit() function inside the xdebug-path-mappings file or should I return to the run-cli file to centralize process.exit functions ?

Good question! Would throw new Error() suffice? AFAIR CLI has an error handler that already calls exit()

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

adamziel · 2025-10-15T10:01:30Z

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

+			// Then, if xdebug, and experimental IDE are enabled,
+			// recreate the symlink pointing to the temporary
+			// directory and add the new IDE config.
+			if (args.xdebug && args.experimentalIde) {


cc @brandonpayton for reviews

@brandonpayton and @adamziel, your reviews are warmly welcomed in this pull request, since I am not sure I will list all the use cases.

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

adamziel · 2025-10-15T15:33:13Z

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

+			(c: { $: { name: string } }) => c.$.name === name
+		);
+		if (!servers) {
+			component.servers[0].server.push(server);


this line keep failing for me, every part of this expression may be missing (like it was in my config).

I had this same experience and believe I've fixed it now.

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

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

+		);
+		if (!component) {
+			config.project.component = [];
+			config.project.component.push({


should we set component to the pushed element?

This should be fixed now.

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

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

9 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

adamziel reviewed Oct 15, 2025

View reviewed changes

packages/playground/cli/src/xdebug-path-mappings.ts Outdated Show resolved Hide resolved

adamziel reviewed Oct 15, 2025

View reviewed changes

packages/playground/cli/src/xdebug-path-mappings.ts Outdated Show resolved Hide resolved

adamziel reviewed Oct 15, 2025

View reviewed changes

mho22 added 2 commits October 15, 2025 15:25

replace JSON.parse with JSONC parser

2db6d02

Add --experimental-ide=vscode|phpstorm and create config file if non …

7f6ce1c

…existent

adamziel reviewed Oct 15, 2025

View reviewed changes

brandonpayton added 6 commits October 18, 2025 10:41

Merge branch 'trunk' into add-xdebug-path-mappings-with-experimental-ide

6a197d7

Allow mapping current dir

5593471

Add explicit host and port args

4d0a9cc

Fix bug when PhpStorm component is not found

e201565

Avoid issues seen with setting PhpStorm server config

84412a9

Log errors with logger.error() instead of console.log()

f203470

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

Are you sure you want to change the base?

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

Conversation

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

Uh oh!

Motivation for the change, related issues

Implementation details

Next

Testing Instructions (or ideally a Blueprint)

Uh oh!

adamziel commented Oct 15, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adamziel commented Oct 15, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adamziel commented Oct 15, 2025

Uh oh!

adamziel commented Oct 15, 2025

Uh oh!

brandonpayton commented Oct 18, 2025

Uh oh!

brandonpayton commented Oct 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

brandonpayton commented Oct 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

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

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

mho22 commented Oct 14, 2025 •

edited

Loading

brandonpayton commented Oct 18, 2025 •

edited

Loading

brandonpayton commented Oct 18, 2025 •

edited

Loading

adamziel commented Oct 18, 2025 •

edited

Loading