Add Xdebug support by wojtekn · Pull Request #2242 · Automattic/studio

wojtekn · 2025-12-12T09:50:30Z

Related issues

Fixes STU-1156

Proposed Changes

Add Xdebug support for WordPress sites with beta feature flag
Implement UI toggle in Edit Site Details modal with one-site-at-a-time constraint
Add full persistence across app restarts (site details, storage, and IPC layer)
Show tooltip when Xdebug is enabled on another site
Show Xdebug status in site's Settings

Xdebug enabled for a site	Restarting site on save	Xdebug not available for other site

Testing Instructions

Test feature in Studio

Enable "Xdebug Support" beta feature in Settings → Beta Features
Open Edit Site Details for any site
Check "Enable Xdebug" checkbox and save
Verify site restarts ~~and console shows "Enabling Xdebug support"~~
Open Edit Site Details again - verify checkbox remains checked
Restart the app - verify Xdebug setting persists
Try enabling Xdebug on a second site - verify checkbox is disabled with tooltip explaining why
Disable Xdebug on first site - verify second site's checkbox becomes enabled

Test debugging in IDE

I used PhpStorm:

Create a site
Enable Xdebug and start the site
Open the site in PhpStorm
To stop breaking at the first line in PHPStorm, open Settings > PHP > Debug > Xdebug:
- Disable > Force break at first line when no path mapping specified
- Disable > Force break at first line when a script is outside the project
Open WP Admin using link in Studio
In PhpStorm, open the path mapping notification (or navigate to PHP|Servers) and configure mapping for your site's server:
- Host: localhost:8884
- Port: 80
- File directory: /Users/USERNAME/Studio/SITEDIR
- Absolute path on the server: /wordpress
Add a breakpoint somewhere, e.g. in wp-config.php file
Refresh WP Admin
Confirm PhpStorm stops execution on the breakpoint

Pre-merge Checklist

Have you checked for TypeScript, React or other console errors?

github-actions · 2025-12-12T12:46:21Z

📊 Performance Test Results

Comparing bc4a134 vs trunk

site-editor

Metric	trunk	`bc4a134`	Diff	Change
load	12909.00 ms	10584.00 ms	-2325.00 ms	🟢 -18.0%

site-startup

Metric	trunk	`bc4a134`	Diff	Change
siteCreation	22537.00 ms	22481.00 ms	-56.00 ms	🟢 -0.2%
siteStartup	9019.00 ms	9015.00 ms	-4.00 ms	🟢 -0.0%

Results are median values from multiple test runs.

Legend: 🟢 Improvement (faster) | 🔴 Regression (slower) | ⚪ No change

bcotrim

Works great! Amazing to see this coming to Studio

Have you considered adding the Xdebug flag in the site details section?

bcotrim · 2025-12-17T11:32:13Z

+										disabled={ ! xdebugEnabledSite || xdebugEnabledSite.id === selectedSite?.id }
+										text={ sprintf(
+											__(
+												'Xdebug is currently enabled for "%s" site. Disable it there first to enable it for this site.'


Have you considered allowing the user to enable here with a notice that it will disable the other site?

The current flow requires ~6 steps:

close modal → switch site → open modal → disable Xdebug → save → switch back → open modal → enable Xdebug.

A single confirmation would be much smoother.

What do you think?

Yes, but I wanted to avoid overcomplicating this in this initial Beta Feature release.

This is a bit of a rabbit hole. If Studio disabled Xdebug for all sites, it should restart them. If it restarts sites, it should first ask users if they want to restart them.

bcotrim · 2025-12-17T11:37:46Z

 							</div>
+
+							{ isXdebugFeatureEnabled && (
+								<div className="flex flex-col gap-2 mt-4 p-4 border border-a8c-gray-200 rounded">


The current disabled state does not look very clear in my opinion. It uses the disabled format for the checkbox but the label could also have some visible changes.
The tooltip provides all the information, but we could make it clear to the user that the option is disabled just by looking at it:

What do you think?

I changed it in bc36147

sejas

Code looks good. I confirm it adds a feature flag, and enables the Xdebug parameter when the checkbox is active. I confirm the site property enableXdebug is saved in one site at a time in Studio settings file.

I was not able to make it work with Cursor, VSCode and PhpStorm. @wojtekn, I would appreciate pairing to double check my testing steps. I followed your testing instructions and also those provided in https://make.wordpress.org/playground/2025/11/24/debugging-with-xdebug-is-now-available-in-wordpress-playground/

I agree with @bcotrim's suggestion. It would be great if users could enable Xdebug on any site, and Studio could automatically remove the flag from the previous site. Maybe we could display a dismissible modal to confirm that action.

A couple of ideas to improve the UI that could be follow-ups:

1. Make the checkbox block consistent with Use custom domain and Enable HTTPS

I suggest making the checkbox more consistent between them, by removing the border around the Xdebug option or adding the border to the rest of checkboxes.

2. Add the action to Enable/Disable Xdebug in the site actions menu.

Enable Xdebug would automatically disable the option from any other site, and start or restart the site.

3. Replace the green dot with a green 🪲 when Xdebug is running in a given site.

PhpStorm and Cursor display the play button like this:

sejas · 2025-12-17T12:35:06Z

+		// Enable Xdebug support if requested
+		if ( options.enableXdebug ) {
+			console.log( __( 'Enabling Xdebug support' ) );
+			args.xdebug = true;


Should we also add experimentalUnsafeIdeIntegration argument or is not necessary? I tried it to add it, but it didn't help during my testing.

args.experimentalUnsafeIdeIntegration = [ 'vscode', 'phpstorm' ];`

No, because it's experimental and unsafe :D I tested it, and besides being broken, it was only updating IDE configs. I think it's better if Studio enables user to use Xdebug, instead of modifying their IDE configs.

bcotrim · 2025-12-17T12:56:17Z

I was not able to make it work with Cursor, VSCode and PhpStorm.

I had some issue and was missing the pathMappings in VSCode. Sharing my launch.json in case it helps

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/wordpress": "${workspaceFolder}"
      }
    }
  ]
}

Replace the green dot with a green 🪲 when Xdebug is running in a given site.

❤️ I love this idea.

wojtekn · 2025-12-17T15:04:43Z

Have you considered adding the Xdebug flag in the site details section?

Good idea. Added in 24204af

wojtekn · 2025-12-17T15:08:27Z

1. Make the checkbox block consistent with Use custom domain and Enable HTTPS

I suggest making the checkbox more consistent between them, by removing the border around the Xdebug option or adding the border to the rest of checkboxes.

Thanks, I updated it in 1bd4aa1

Add the action to Enable/Disable Xdebug in the site actions menu.

The site context menu has "Edit site..." which contains Xdebug field, so I would hold with this change at this point.

Replace the green dot with a green 🪲 when Xdebug is running in a given site.

Sounds cool, but I would hold with this under this PR, and we could push follow-up after we check it more with the design team.

@sejas let's pair tomorrow to see how it works on your environment.

bcotrim · 2025-12-17T17:24:33Z

@wojtekn I added the CLI changes to support x-debug flag.
Please let me know if you find any regressions.

I also implemented the studio site set-xdebug to follow the other set-* commands we have.
cc @fredrikekelund if you want to take a quick look at the implementation

bcotrim

Thanks @wojtekn for the adjustments!
The UI looks great.
Since I've made some changes to this PR I'll leave the approval for another reviewers but it's a LGTM on my side 👍

wojtekn · 2025-12-17T17:28:37Z

Thanks @bcotrim .

sejas

It worked for me. I tested it using Cursor and the this launch.json and it worked great. @bcotrim, thanks for sharing the pathMappings trick.

Note that the breakpoint set in wp-config.php was ignored, while breakpoints in other parts of the app, such as in a plugin, worked correctly.

I just noticed that we are not consistent with the bold/regular font weight in the checkbox. I recommend making them consistent or creating a new issue to discuss that.

wojtekn · 2025-12-18T14:15:12Z

Note that the breakpoint set in wp-config.php was ignored, while breakpoints in other parts of the app, such as in a plugin, worked correctly.

It works for me when I debug in PhpStorm - I can set breakpoints in wp-config.php file.

I just noticed that we are not consistent with the bold/regular font weight in the checkbox. I recommend making them consistent or creating a new issue to discuss that.

I fixed this, good catch.

I tested it again after Studio CLI changes, and it works fine, too. The only change is that console output doesn't show Playground CLI messaging so "Enabling Xdebug support" is not visible there.

# Conflicts: # src/storage/user-data.ts

wojtekn marked this pull request as ready for review December 12, 2025 11:45

wojtekn requested a review from a team December 12, 2025 11:46

wojtekn self-assigned this Dec 12, 2025

bcotrim reviewed Dec 17, 2025

View reviewed changes

sejas reviewed Dec 17, 2025

View reviewed changes

bcotrim force-pushed the add/xdebug-support branch from 358d0c8 to 60ab25c Compare December 17, 2025 17:16

bcotrim requested a review from fredrikekelund December 17, 2025 17:18

bcotrim reviewed Dec 17, 2025

View reviewed changes

sejas approved these changes Dec 18, 2025

View reviewed changes

wojtekn added 14 commits December 19, 2025 15:14

Add type definitions for Xdebug support

bbd313c

Add Xdebug Support beta feature definition

8ff5cf1

Add IPC handler to find Xdebug-enabled site

ed67c08

Use enableXdebug option instead of hardcoded condition

42d1303

Thread enableXdebug option through Playground CLI provider

84bab4b

Pass enableXdebug from site details to provider

6f8925f

Expose getXdebugEnabledSite handler in preload script

5b7df93

Fix preserving Xdebug option in files

1985cea

# Conflicts: # src/storage/user-data.ts

Add Xdebug UI in site edit form

7b39fc0

Fix comparison to accep undefined value

3d437a7

Add test case for getXdebugEnabledSite

a2d06ac

Remove unnecessary commented out code

98aa2af

Add Xdebug status in Site details in Settings tab

403aa0c

Grey out the Xdebug section if it is disabled

0f052c8

wojtekn added 4 commits December 19, 2025 15:14

Simplify Xdebug UI, add learn more link, improve disabled styling

a8082b2

Update test to account for Disabled Xdebug option

6fc59e4

Remove bold to unify label with other parts

09be845

Wrap Xdebug in site Settings with beta feature flag check

3241fe7

wojtekn force-pushed the add/xdebug-support branch from 7223493 to 3241fe7 Compare December 19, 2025 14:19

wojtekn added 2 commits December 19, 2025 16:06

Fix tests

ff3cb45

Add missing enableXdebug

54cc6b7

wojtekn merged commit 6e2bda4 into trunk Dec 19, 2025
9 checks passed

wojtekn deleted the add/xdebug-support branch December 19, 2025 15:50

shivapoudel mentioned this pull request Dec 29, 2025

Feature Request: Add support for PHP extensions required for object caching #2329

Closed

epeicher mentioned this pull request Jan 16, 2026

Fix timeout starting sites with XDebug enabled using the packaged app #2410

Merged

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add Xdebug support - #2242

Add Xdebug support#2242
wojtekn merged 20 commits into
trunkfrom
add/xdebug-support

wojtekn commented Dec 12, 2025 •

edited

Loading

github-actions Bot commented Dec 12, 2025 •

edited

Loading

bcotrim left a comment •

edited

Loading

bcotrim Dec 17, 2025

wojtekn Dec 17, 2025

bcotrim Dec 17, 2025

wojtekn Dec 17, 2025

Uh oh!

sejas left a comment •

edited

Loading

sejas Dec 17, 2025 •

edited

Loading

wojtekn Dec 17, 2025

bcotrim commented Dec 17, 2025

wojtekn commented Dec 17, 2025

wojtekn commented Dec 17, 2025

bcotrim commented Dec 17, 2025

bcotrim left a comment

wojtekn commented Dec 17, 2025

sejas left a comment •

edited

Loading

wojtekn commented Dec 18, 2025

Uh oh!

Labels

3 participants

Uh oh!

Conversation

wojtekn commented Dec 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Related issues

Proposed Changes

Testing Instructions

Test feature in Studio

Test debugging in IDE

Pre-merge Checklist

github-actions Bot commented Dec 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📊 Performance Test Results

site-editor

site-startup

bcotrim left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

bcotrim Dec 17, 2025

Choose a reason for hiding this comment

wojtekn Dec 17, 2025

Choose a reason for hiding this comment

bcotrim Dec 17, 2025

Choose a reason for hiding this comment

wojtekn Dec 17, 2025

Choose a reason for hiding this comment

Uh oh!

sejas left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

sejas Dec 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

wojtekn Dec 17, 2025

Choose a reason for hiding this comment

bcotrim commented Dec 17, 2025

wojtekn commented Dec 17, 2025

wojtekn commented Dec 17, 2025

bcotrim commented Dec 17, 2025

bcotrim left a comment

Choose a reason for hiding this comment

wojtekn commented Dec 17, 2025

sejas left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

wojtekn commented Dec 18, 2025

Uh oh!

Labels

3 participants

wojtekn commented Dec 12, 2025 •

edited

Loading

github-actions Bot commented Dec 12, 2025 •

edited

Loading

bcotrim left a comment •

edited

Loading

sejas left a comment •

edited

Loading

sejas Dec 17, 2025 •

edited

Loading

sejas left a comment •

edited

Loading