Debugging WordPress PHP Code with Xdebug and VS Code

Xdebug is a PHP extension that enables step-through debugging, stack traces, and code coverage. Combined with VS Code and the PHP Debug extension, you can set breakpoints, inspect variables, and step through WordPress execution line by line — far more powerful than scattering var_dump() calls everywhere.

Problem: How do you set up step-through debugging for WordPress PHP code in VS Code instead of scattering var_dump() calls throughout your codebase?

Solution: Install Xdebug, configure it in php.ini to connect back to VS Code's PHP Debug extension, set breakpoints in the editor, and start a debugging session — execution pauses at any line and lets you inspect all variables and the full call stack.

Install Xdebug (on Ubuntu/Debian):

sudo apt install php-xdebug
# or via PECL if the package is not available
sudo pecl install xdebug

Configure Xdebug in php.ini (or a separate 20-xdebug.ini):

[xdebug]
zend_extension=xdebug.so
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.log=/tmp/xdebug.log

VS Code launch.json configuration for listening to Xdebug:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/var/www/html/wp-content/themes/mytheme": "${workspaceFolder}"
            }
        }
    ]
}

WordPress-specific debug settings to add in wp-config.php alongside Xdebug:

define( 'WP_DEBUG',         true );
define( 'WP_DEBUG_LOG',     true );   // logs to wp-content/debug.log
define( 'WP_DEBUG_DISPLAY', false );  // don't display errors on screen
define( 'SAVEQUERIES',      true );   // log all DB queries to $wpdb->queries

NOTE: Never enable WP_DEBUG_DISPLAY or Xdebug's start_with_request=yes on a public production server — it exposes error details and can significantly slow every request. Keep a separate php.ini or wp-config.php for local development.