Xdebug in WordPress Studio

WordPress Studio includes Xdebug support for local sites. Xdebug is a debugging extension for PHP that enables you to set breakpoints, inspect variables, and step through your code.

Enabling Xdebug

1. Select the site you want to debug.
2. Navigate to the Settings tab.
3. Click “Edit site.”
4. Navigate to the “Debugging” tab.
5. Check the “Enable Xdebug” checkbox.
6. Click Save.

The site will restart automatically with Xdebug enabled.

Important limitations

• Only one site at a time: Xdebug can only be enabled for a single site at once. To enable it for a different site, you must first disable it on the current site.
• Performance impact: Xdebug may slow down site performance. Disable it when not actively debugging.

Using Xdebug with your IDE

Once Xdebug is enabled for a site, you can connect your IDE (code editor) to debug WordPress plugins, themes, and core code.

Studio’s default Native PHP runtime usually does not require path mapping in your editor. If your site uses the Sandbox runtime, configure path mapping from Studio’s /wordpress server path to your local site folder.

Visual Studio Code setup

1. Install the PHP Debug extension.
2. Create a .vscode/launch.json file in your project:

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

3. If your site uses the Sandbox runtime, add pathMappings to the configuration:

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

4. Set breakpoints in your code.
5. Start the debugging session in Visual Studio Code (Run → Start Debugging).
6. Navigate to your site in the browser to trigger the breakpoints.

PhpStorm Setup

1. Go to Settings → PHP → Debug.
2. Verify that the Xdebug port is set to 9003.
3. To stop breaking at the first line:
   • Disable “Force break at first line when no path mapping specified”
   • Disable “Force break at first line when a script is outside the project”
4. If your site is using the Sandbox runtime, configure path mappings:
   • PhpStorm may ask you to configure path mappings when the first Xdebug connection is received.
   • Map Studio’s /wordpress server path to your local Studio site folder.
   • You can also configure this manually in Settings → PHP → Servers.
5. Enable “Start listening for PHP Debug Connections” from the toolbar.
6. Set breakpoints in your code.
7. Navigate to your site in the browser to trigger the breakpoints.

Learn more

For more details about how Xdebug works with the Sandbox runtime, see the WordPress Playground Xdebug documentation.