Title: Getting Started with Xdebug Published: July 15, 2026 Last modified: July 16, 2026 --- # Getting Started with Xdebug ## In this article * [PHP WASM CLI vs Playground CLI](https://developer.wordpress.org/playground/developers/xdebug/getting-started/?output_format=md#php-wasm-cli-vs-playground-cli) * [Quick start with npx](https://developer.wordpress.org/playground/developers/xdebug/getting-started/?output_format=md#quick-start-with-npx) * [Starting with IDE integration](https://developer.wordpress.org/playground/developers/xdebug/getting-started/?output_format=md#starting-with-ide-integration) * [Early Access: DevTools debugger](https://developer.wordpress.org/playground/developers/xdebug/getting-started/?output_format=md#early-access-devtools-debugger) [ Back to top](https://developer.wordpress.org/playground/developers/xdebug/getting-started/?output_format=md#wp--skip-link--target) This guide shows you how to enable Xdebug in WordPress Playground and start debugging your code. ## 󠀁[PHP WASM CLI vs Playground CLI](https://developer.wordpress.org/playground/developers/xdebug/getting-started/?output_format=md#php-wasm-cli-vs-playground-cli)󠁿 First, Xdebug is present in two different CLIs: * **`@php-wasm/cli`**: Run standalone PHP scripts. Use this when debugging PHP code without needing a WordPress environment. * **`@wp-playground/cli`**: Run a full WordPress installation. Useful for debugging WordPress plugins, themes, or core functionality. For this guide, we’ll use `@wp-playground/cli`. If you’re not familiar with the tool, we recommend reading the [`@wp-playground/cli` guide](https://developer.wordpress.org/playground/developers/local-development/wp-playground-cli), but the same process can also be applied to debugging PHP applications with `@php- wasm/cli`. ## 󠀁[Quick start with npx](https://developer.wordpress.org/playground/developers/xdebug/getting-started/?output_format=md#quick-start-with-npx)󠁿 The fastest way to get started is using npx, which doesn’t require installation: ```bash npx @wp-playground/cli@latest server --xdebug ``` This starts WordPress on `http://127.0.0.1:9400` with Xdebug enabled. Now you can connect a debugger. Only one project can be debugged at a time. ## 󠀁[Starting with IDE integration](https://developer.wordpress.org/playground/developers/xdebug/getting-started/?output_format=md#starting-with-ide-integration)󠁿 Similar to the process with DevTools, let’s use the same plugin code from before to debug with VS Code, and add the `--experimental-unsafe-ide-integration=vscode` flag. This flag will optimize the setup process for VS Code. If you’re working with PhpStorm, add the `--experimental-unsafe-ide-integration=phpstorm` flag. This flag is marked as `unsafe` because it edits the IDE config files to set Xdebug path mappings and web server details. **CAUTION:** If there are bugs, this feature may cause your IDE configuration files to break. Please consider backing up your IDE configs before using this feature. To debug in VS Code, you’ll need the following prerequisites: 1. An extension to add PHP profiling support, for example, [PHP Debug](https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug) or another debugger extension to your preference. 2. Have a `.vscode/` folder. 3. Enable breakpoints in your IDE. Some IDEs come with this feature disabled, so be aware of this detail. If everything is ready, you run the command: ```bash npx @wp-playground/cli@latest server --xdebug --experimental-unsafe-ide-integration=vscode --auto-mount ``` If you don’t have a `.vscode/launch.json` file, the terminal will create a file similar to this: ```language-JSON { "configurations": [ { "name": "WP Playground CLI - Listen for Xdebug", "type": "php", "request": "launch", "port": 9003, "pathMappings": { "/": "${workspaceFolder}/.playground-xdebug-root", "/wordpress/wp-content/plugins/test-xdebug": "${workspaceFolder}/" } } ] } ``` Now, you can go to your code, add the breakpoints, start the debugging session named by your IDE, and happy testing. ![Xdebug in action on VS Code](https://i0.wp.com/raw.githubusercontent.com/WordPress/ wordpress-playground/refs/heads/trunk/packages/docs/site/static/img/developers/xdebug/ xdebug-in-action-on-vscode.webp?ssl=1) ## 󠀁[Early Access: DevTools debugger](https://developer.wordpress.org/playground/developers/xdebug/getting-started/?output_format=md#early-access-devtools-debugger)󠁿 Playground CLI ships an **unstable, highly exploratory** workflow that enables debugging PHP programs using Chrome DevTools. To try it, use the `--experimental-devtools` flag: ```bash npx @wp-playground/cli@latest server --xdebug --experimental-devtools ``` The terminal will display a URL to connect to Chrome DevTools: ```bash Starting a PHP server... Setting up WordPress latest Resolved WordPress release URL: https://downloads.w.org/release/wordpress-6.8.3.zip Fetching SQLite integration plugin... Booting WordPress... WordPress is running on http://127.0.0.1:9400 with 1 worker(s) Starting XDebug Bridge... Connect Chrome DevTools to CDP at: devtools://devtools/bundled/inspector.html?ws=127.0.0.1:9229 Chrome connected! Initializing Xdebug receiver... XDebug receiver running on port 9003 Running a PHP script with Xdebug enabled... ``` By clicking on the provided URL, for example, `devtools://devtools/bundled/inspector. html?ws=127.0.0.1:9229`, you can access DevTools connected to your application, with the ability to inspect all files of a WordPress instance. ![Chrome Devtools integrated with Xdebug](https://i0.wp.com/raw.githubusercontent. com/WordPress/wordpress-playground/refs/heads/trunk/packages/docs/site/static/img/ developers/xdebug/playground-xdebug-on-devtools.webp?ssl=1) For a more practical example, let’s debug a plugin that has the following code: ```language-PHP