Issues when Debugging PHP in VSCode using Docker and WSL2

Forget about the other answers. They are working but too complicated in my opinion.

The problem is, that you can't connect to xdebug.

The solution is to tell xdebug to set remote_host to host.docker.internal. Everything from there is available to localhost. Now you only have to listen inside Visual Studio Code to localhost via hostname.

Et voilà. Now you can debug things invoked by your browser, inside your phpunit tests or within your commandline scripts.

Complete Example

launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for XDebug",
            "type": "php",
            "request": "launch",
            "port": 9000,
            "pathMappings": {
                "/var/www/html/": "${workspaceRoot}"
            },
            "hostname": "localhost"
        }
    ]
}

php.ini

[XDebug]
xdebug.remote_enable = 1
xdebug.remote_autostart = 1
xdebug.remote_host = host.docker.internal
xdebug.remote_port = 9000

Update for XDebug 3

launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for XDebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/var/www/html/": "${workspaceRoot}"
            },
            "hostname": "localhost"
        }
    ]
}

php.ini

[XDebug]
xdebug.mode = develop
xdebug.start_with_request = yes
xdebug.client_host = host.docker.internal
xdebug.client_port = 9003

I have been struggling with PHP xdebug in Docker using WSL2 as well. It all comes down to the remote host.

What is your xdebug config in php.ini? You should set xdebug.remote_host to your WSL2 local IP address (which you can get in a terminal using hostame -I).

I have tried several times to set the remote host IP address in my Docker—composing a file to pass to the container on startup—but it always fails. Thanks to another StackOverflow answer, however, I have a solution for that too:

In WSL2, set an environment variable for your local IP in your .bashrc file. I have set mine to

export IP=$(hostname -I)

In your Docker compose file for the PHP service, pass the IP address as a new host with the extra_hosts key. For compose v3.2 it is

extra_hosts:
 - "docker.host:${IP}"

You can look here for other compose versions: https://docs.docker.com/compose/compose-file/

Finally, edit your php.ini file for xdebug to have this line:

xdebug.remote_host=docker.host

Your container will be able to reach the WSL2 distribution with your docker.host and connect to the port you set for xdebug.

I spent a lot of time figuring this out, mainly because WSL2 was released officially a few days ago and there are not many guides about it. It was not so complicated in the end, but without the extra_hosts key I could not get the WSL2 IP address to work. It was in the container and in xdebug config, but I always got an error about the resource being unavailable, so don't forget it

The answer by @Romain-prevost is definitely the easiest and best way. If for some reason you can't get that to work, there is another alternative.

host.docker.internal will likely be reachable from within your container, but is a 192.* address by default, and is your Windows-based Docker IP. So you would need to set up forwarding from your Windows host into your WSL2 instance. This is outlined in this script in this issue at Github/WSL. You would simply change the ports to 9000 in that script. You could also use WSL2-Host to have a named entry in your hosts file for that IP and modify the script further to both restrict calling/receiving IPs.