Fellyph Cintra 6:01 pm on November 24, 2025  

Debugging with Xdebug is now available in WordPress Playground

Have you ever faced a moment where your application wonā€™t run, and you need to understand the steps that led to the failure? Xdebug is the perfect tool for this, but debugging a PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. https://www.php.net/manual/en/preface.php. application inside WebAssembly was a challenge until one of the most recent updates to WordPress Playground.

WordPress Playground now supports Xdebug. You can connect Visual Studio Code and PhpStorm IDEs to debug PHP code with breakpoints, step-by-step execution, and variable inspection. This experimental feature needs your feedback.

What can you do with Xdebug?

Connect Xdebug in Playground to your IDE to:

  • Set breakpoints ā€” Pause execution on specific lines
  • Step through code ā€” Move line by line during execution
  • Inspect variables ā€” View values during execution
  • Evaluate expressions ā€” Test code in the current context

Getting Started with Xdebug

Letā€™s debug a simple pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party using the Playground CLI and Xdebug to demonstrate this feature. But donā€™t worry, this feature is also available for the PHP-WASM CLICLI Command Line Interface. Terminal (Bash) in Mac, Command Prompt in Windows, or WP-CLI for WordPress..

Prerequisites

You need:

  • Node.js 23 or higher and npm installed
  • @wp-playground/cli version 3.0.20 or higher
  • Visual Studio Code with the PHP Debug extension installed or the Xdebug extension configured in PhpStorm.

For Visual Studio Code and IDEs forked from it, we do recommend the official PHP Debug extension from Xdebug.org. This is required for debugging PHP in VS Code, not a specific requirement for WordPress Playground.

Configuration Steps

1. Prepare your code for testing

For this demo, I will use the following code. It displays a message in the WordPress Admin Dashboard. To see this code in action, you must access the /wp-admin/ address:

<?php
/**
 * Plugin Name: Simple Admin Message
 * Description: Displays a simple message in the WordPress admin
 * Version: 1.0
 * Author: Playground Team
 */


// Prevents direct access
if (!defined('ABSPATH')) {
    exit;
}


// Displays admin notice
function sam_display_admin_message() {
    $message = 'Hello! This is a simple admin message.';
    ?>
    <div class="notice notice-info is-dismissible">
        <p><?php _e($message, 'simple-admin-message'); ?></p>
    </div>
    <?php
}
add_action('admin_notices', 'sam_display_admin_message');

2. Configure your IDE to listen for Xdebug

The WordPress Playground CLI has a flag that can help developers if they donā€™t have Xdebug configured: --experimental-unsafe-ide-integration=, which currently supports two IDEs: vscode and phpstorm.

This will save time by generating the necessary files to get your debugging started.

Visual Studio Code

To start debugging, VS Code needs the .vscode/launch.json file. Here is an example:

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

Start the debugger with F5 or ā€œRun > Start Debuggingā€. Run the plugin with the Playground CLI to see the execution stop when the code hits a breakpoint.

To debug the plugin above, we can initialize the plugin in the Playground CLI with the following code:

npx @wp-playground/cli@latest server --xdebug --experimental-unsafe-ide-integration=vscode --auto-mount

PhpStorm

Configure PhpStorm with path mappings and a PHP Remote Debug configuration.

  1. Create a PHP Remote Debug configuration.
  2. Click on Start Listening for PHP Debug Connections.
  3. Run the plugin with the Playground CLI.

To run the plugin with the Playground CLI, execute the command in the terminal:

npx @wp-playground/cli@latest server --xdebug --experimental-unsafe-ide-integration=phpstorm --auto-mount

See the Xdebug documentation in PhpStorm for detailed configuration instructions.

Running Xdebug with PHP-WASM CLI

Another option is to use Xdebug with PHP-WASM CLI, which is useful when you would like to debug only PHP without a WordPress environment.

To run it, you will need to set up Xdebug in your development environment. Once you are ready, add the breakpoints to your PHP file and run the command point to the file that you would like to debug. For example, the file below is located at src/test.php:

<?php

$test = 42; // Set a breakpoint on this line

echo "Output!n";

function test( $output ) {
    echo "Hello Xdebug World!n" . $output . "n";
}

test($test);

At the terminal, you run the command:

 npx @php-wasm/cli@latest --xdebug php/test.php

The result will be starting the debugging mode at the IDE:

A WordPress Playground team effort to solve a complex problem

Bringing Xdebug to WebAssembly required solving technical challenges. The Playground team spent months turning a tracking issue from May 2023 into working code.

Technical Achievement

The WordPress Playground team has made significant strides in integrating Xdebug for in-browser debugging. This effort involved numerous pull requests that tackled a range of technical challenges:

  • Asyncify Extension: Added Xdebug support via asyncify-specific shared extension builds and loaders.
  • IDE Integration Enhancements: Introduced experimental IDE path mappings for seamless debugging between the Playgroundā€™s virtual file system (VFS) and host IDEs.
  • Xdebug Bridge: Enabled the bridge to read files directly from the VFS, aligning breakpoints and source files for consistent debugging experiences.
  • CLI UX Improvements: Refined the CLI experience to prevent breakpoints from interrupting the Playground boot process unnecessarily.
  • DevTools & Debugger Enhancements: Preloaded files for improved DevTools debugging (#2527), added syntax highlighting (#2566), and enhanced array inspections and Xdebug protocol handling (#2409).
  • Upgraded Toolchain (#2910): Upgraded Emscripten to address linker issues, ensuring smooth dynamic loading of shared extensions like Xdebug.

Together, these enhancements have enabled robust step-debugging workflows, bridging the Playgroundā€™s WASM environment with modern IDE capabilities. Additionally, earlier groundwork (#673, #831) on dynamic loading set the foundation for these advancements.

The result? Xdebug in WordPress Playground isnā€™t just functional; it further empowers development and testing entirely in-browser.

Whatā€™s Next

The team continues working to bring Xdebug support to more Playground builds and explore debugging directly within browser developer tools.

Try Xdebug today and share your feedback on the original tracking issue. Check the Xdebug documentation for more configuration instructions, IDE integration guides, and troubleshooting tips.

Props to @zieladam and @yannickdecat