WordPress Development Workflow: Using wp-env with Xdebug and PhpStorm

Debug WordPress with wp-env, Xdebug and PhpStorm

@wordpress/env (wp-env) starts a complete WordPress development environment in Docker with one command, with the current plugin or theme mounted inside. It also has Xdebug built in: one flag enables it, and PhpStorm (or VS Code) can then stop at breakpoints in your plugin, step through the code and inspect variables, instead of var_dump() and error_log().

Problem: A plugin behaves wrongly on one request, and adding error_log() calls and reloading the page is slow. You want breakpoints in PhpStorm for code running in the wp-env container.

Solution: Start wp-env with --xdebug, let PhpStorm listen for Xdebug connections, map the container paths to your local files, and trigger debugging only for the requests you want.

Start wp-env with Xdebug

In the plugin folder, with Docker running:

npx wp-env start --xdebug

This installs and enables Xdebug in the WordPress containers, in debug mode, connecting to your machine on port 9003. Other modes can be combined: --xdebug=debug,coverage also enables code coverage for tests. The site runs at http://localhost:8888 (admin: admin / password).

A minimal .wp-env.json for a plugin:

{
    "phpVersion": "8.2",
    "plugins": [ "." ],
    "config": {
        "WP_DEBUG": true,
        "WP_DEBUG_LOG": true,
        "SCRIPT_DEBUG": true
    }
}

config sets wp-config.php constants; the Xdebug settings come from the command-line flag, not from this file.

PhpStorm

1. Settings → PHP → Debug: Xdebug port 9003 (the default).
2. Settings → PHP → Servers: add a server with host localhost, port 8888, debugger Xdebug, and enable “Use path mappings”. Map your plugin folder to /var/www/html/wp-content/plugins/my-plugin (the folder name inside the container is the name of your local folder).
3. Click “Start Listening for PHP Debug Connections” (the phone icon), and set a breakpoint in your plugin.

Xdebug in wp-env starts a debug session only when the request asks for one. Install the Xdebug Helper extension in the browser, enable it for the localhost:8888 tab, and reload: PhpStorm stops at the breakpoint. Other requests run at normal speed.

Debug WP-CLI and tests

The CLI container has the same Xdebug, and a session can be started with the XDEBUG_SESSION environment variable:

npx wp-env run cli --env-cwd=wp-content/plugins/my-plugin env XDEBUG_SESSION=PHPSTORM wp my-plugin import

For PHPUnit, the tests-cli container runs the tests against a separate test site:

npx wp-env run tests-cli --env-cwd=wp-content/plugins/my-plugin env XDEBUG_SESSION=PHPSTORM vendor/bin/phpunit --filter=Test_Discount

For CLI debugging PhpStorm needs a server entry too; if it asks which server the connection belongs to, choose the one you created and the same path mapping.

When nothing happens

• Check that Xdebug is loaded: npx wp-env run cli php -m | grep -i xdebug.
• Check that PhpStorm is listening and that a firewall does not block port 9003.
• If PhpStorm reports a connection but does not stop, the path mapping is wrong: it cannot match the container path to a local file.

NOTE: wp-env start --xdebug has to be used again after wp-env stop or destroy, otherwise the environment starts without Xdebug. The same setup runs the tests from unit tests with PHPUnit locally in Docker.