Back to Site

Using XDebug

Xdebug is pre-installed in the WP Setup CLI image but is disabled by default. To enable Xdebug, use the --xdebug flag with the wp-setup start command. This will enable XDebug in both CLI containers.

The wp-cli container will start XDebug with debug,develop mode and the wp-test-cli always starts with coverage mode and the --xdebug will also add debug,develop modes.

npx wp-setup start --xdebug

Xdebug IDE Integration

To integrate Xdebug with your IDE, use the following settings. This JSON snippet is tailored for VS Code’s launch.json format (details can be found here), along with the PHP Debug extension. The path mapping is configured for a specific plugin — update this to match the source you are working.

You only need to adapt port and pathMappings to your IDE’s format.

{
	"configurations": [
		{
			"name": "Listen for XDebug",
			"type": "php",
			"request": "launch",
			"port": 9003,
			"pathMappings": {
				"/var/www/html/wp-content/plugins/my-plugin": "${workspaceFolder}/"
			}
		}
	]
}

Once your IDE’s Xdebug settings are configured, simply launch the debugger, set a breakpoint on any line of PHP code, and refresh your browser!

Summary

  1. Start wp-setup with Xdebug enabled: npx wp-setup start --xdebug
  2. Install a suitable Xdebug extension for your IDE if it does not already include one.
  3. Configure the IDE debugger to use port 9003 and point to the correct source files in WP Setup.
  4. Launch the debugger and set a breakpoint on any line of PHP code.
  5. Refresh the URL that your env is running at, and the breakpoint should trigger.