Xdebug 3 Setup for Drupal VM with PHP 8 on Visual Studio Code

I spent far too much time last week working out the right Xdebug configuration for Drupal VM with PHP 8.1.10 using Visual Studio Code. In the off chance someone else is stumbling around the outskirts of day-to-day use cases, here’s a little guidance:

In case you care why

These little details are way outside the purview of my daily coding tasks - but of course the why still interests me. As far as I can tell, PHP 8+ requires Xdebug 3+, and configuration options have significantly changed in Xdebug 3+ including some particularly confusing changes to variable names. For Drupal VM that means editing an xdebug.ini file and then your config.yml followed by re-provisioning your machine. 

While hunting for answers I came across this issue: Does DrupalVM work with Xdebug V3 installed on host?, and then did some digging in the Upgrading from Xdebug 2 to 3 documentation. The piece that particularly mixed me up was that the xdebug.remote_host configuration had changed to a not-at-all-similar-sounding xdebug.client_host.

Anyhow, after some headache the following changes got me back to debugging:

/drupal-vm/provisioning/roles/geerlingguy.php-xdebug/templates/xdebug.ini.j2

Add these lines to the existing declarations:

xdebug.mode={{ php_xdebug_mode }}
xdebug.client_host={{ php_xdebug_client_host }}
xdebug.start_with_request={{ php_xdebug_start_with_request }}

drupal-vm/config.yml

This is my entire Xdebug configuration, so you could overwrite your own with this to get it working then go from there. Many of these options are legacy Xdebug configurations that have no effect, but don't harm anything. The important ones here are php_xdebug_version, php_xdebug_client_host, php_xdebug_start_with_request, and php_xdebug_mode - although this does depend on your configuration needs.

# XDebug configuration; much of these are legacy options and not strictly necessary
php_xdebug_version: 3.1.0
php_xdebug_default_enable: 1
php_xdebug_coverage_enable: 1
php_xdebug_cli_disable: yes
php_xdebug_remote_enable: 1
php_xdebug_remote_connect_back: 1
php_xdebug_idekey: VSCODE
php_xdebug_max_nesting_level: 256
php_xdebug_client_host: "{{ ansible_default_ipv4.gateway }}"
php_xdebug_mode: debug
php_xdebug_start_with_request: yes

.vscode/launch.json

This is a standard VSCode Listen for Xdebug launch.json - just FYI using the default port of 9003 did turn out to be important in my case.

{
    "version": "0.2.0",
    "configurations": [
      {
        "name": "Listen for XDebug",
        "type": "php",
        "request": "launch",
        "port": 9003,
        "pathMappings": {
          "/var/www/my-project-webroot": "${workspaceRoot}/repo"
        }
      }
    ]
  }

Make sure you vagrant reload --provision after saving all your changes. You may want to patch xdebug.ini.j2, too, instead of just hacking it.

Happy debugging!