Install Xdebug on VSCode with Docker and WSL

In a Docker + WSL environment the most important part of the Xdebug setup is making the container reach the host editor.

Install Xdebug in the PHP image, then configure it like this:

xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=host.docker.internal
xdebug.client_port=9003

In VSCode, install the PHP Debug extension and add a launch configuration:

{
  "name": "Listen for Xdebug",
  "type": "php",
  "request": "launch",
  "port": 9003,
  "pathMappings": {
    "/var/www/html": "${workspaceFolder}"
  }
}

If breakpoints are not hit, verify the container path first. Most Xdebug issues in this setup are caused by an incorrect pathMappings value.