Windows 10, WSL2, Docker, PHPStorm, Xdebug

I struggled a bit to get Xdebug working with PHPStorm on my Windows 10 development machine with WSL2 and Docker. After a bit of research, I finally found a configuration that works for me.

Apparently, I did not configure Xdebug and PHPStorm since I moved to my Windows 10 development platform 2 years ago. While trying to do so now, I ran into the issue that Xdebug did not connect to my PHPStorm instance and thus I could not properly debug. Back in my Linux days it seemed easier to get the connection between Xdebug and PHPStorm working, I even blogged about my old setup a while ago.

Current situation: I have installed PHPStorm via Jetbrains Toolbox App and Docker Desktop on my Windows 10 box. Development happens in a WSL2 Ubuntu 20.04 instance in which I start the needed Docker containers. In this specific setup, I also have a Traefik Proxy instance running as a reverse proxy as well as to handle the SSL termination.

In the Xdebug configuration, I enabled xdebug.discover_client_host = true to allow Xdebug to detect the client IP by itself. That did not seem to work, so I tried to configure the IP address of my Windows 10 host via the xdebug.client_host but that did not work either.

While searching for a solution on the internet, I came across a YouTube video by Derick Rethans explaining how to properly configure things for my setup. As always, it's easier than you think ;)

In the end, this is what my xdebug.ini configuration looks like:

zend_extension=xdebug
xdebug.mode=develop,debug
xdebug.start_with_request=yes
xdebug.discover_client_host=0
xdebug.client_host=host.docker.internal

The bottom 3 settings are important:

• xdebug.start_with_request=yes makes sure to start Xdebug with each incoming request
• xdebug.discover_client_host=0 instructs Xdebug to not be smart and detect the client host based on HTTP headers
• xdebug.client_host=host.docker.internal tells Xdebug to connect to the host host.docker.internal

But what's that host host.docker.internal? Well, that's something we need to define. In the docker-compose.yml file we add an extra_hosts entry like this:

  phpfpm:
    build:
      context: docker/phpfpm
      dockerfile: Dockerfile
    extra_hosts:
      - "host.docker.internal:host-gateway"

The host-gateway will automatically resolve to your host computer which is exactly what we want. No need to hardcode IP addresses that may change over time. And in my Windows 10 & WSL 2 environment, it seems to perfectly resolve to the IP address of my Windows host which is running PHPStorm. Once I configure PHPStorm to listen for incoming debug requests it instantly worked.