Using xdebug with Windows 10, WSL2, Docker and VS Code

README.md

Configuring xdebug to work with Windows 10 (WSL2), Docker and VS Code

Configuring your dev environment to be able to use xdebug when you're working on Windows 10 (with WSL2) and Docker with VS Code can be (a bit) tricky.
This is a quick reminder of how I've done that.

Configuring the environment

1. Install and configure xdebug in Docker

   # Install xdebug according to the Docker image you're using
   RUN pecl install xdebug
   COPY xdebug.ini  $PHP_INI_DIR/conf.d/

   (cf. the xdebug.ini file in this gist)

2. Setup VS Code

   PHP Debug is the extension to debug PHP in VS Code.
   Once installed and your project opened, create the configuration file .vscode/lauch.json
   (cf. the lauch.json file in this gist)

   Two impostant things here :

   • The port must match the one defined in xdebug.ini
   • pathMappings must associate the path of your app on Docker and the path of your VSCode project
     (do not use an absolute or relative path. You must use the variables VSCode provides)

3. Configure Windows Defender Firewall

   Even after starting debugging, breakpoints might never be hitten. That's because of Windows Defender Firewall.
   It treats WSL as a public network by default and blocks access. This can be fixed by adding a rule. Just run (with Powershell):

   New-NetFirewallRule -DisplayName "WSL" -Direction Inbound  -InterfaceAlias "vEthernet (WSL)"  -Action Allow

   More about this issue here

Debug a request

Now that your environment is set up, it's time to debug!

1. Run a debugging session

   In the left side panel of VSCode, select the "Debug view" (or just press Ctrl + Shift + D), make sure that the chosen configuration is the one you added in the file lauch.json. Then click on the little green triangle titled "Start debugging".

2. Add breakpoints wherever you want to debug your app

3. Refresh your browser!

Optional:
You can add Xdebug helper to debug in Chrome.

Yeah!
You're ready to create an awesone app!

Want to know more on debugging with xdebug?
Let's read the 'Step Debugging' doc

lauch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for XDebug",
            "type": "php",
            "request": "launch",
            // I changed the port, by default xdebug 3 uses 9003
            "port": 5902,
            "pathMappings": {
                "/var/www/my-app": "${workspaceFolder}"
            },
            "hostname": "localhost"
        },
    ]
}

xdebug.ini

zend_extension=xdebug

xdebug.mode=debug,develop
xdebug.client_host=host.docker.internal
xdebug.client_port=5902 #same port as in launch.json

#Uncomment this line to enable xdebug for each request
#xdebug.start_with_request=yes

Hi,
thanks for the guide!
I am running Win11 and it should be the same, but its not working for me. I ran the powershell command, and I added a rule for ESET Internet Security, but it still wont hit the breakpoint.

Any suggestions?

Thanks in advance

Hi,

I just followed your guide but even though I am not able to check anything because every time I refresh the page it only refreshes without showing me any data.

Is there a way I can talk to you and get your services for support?

I've followed all the steps as well, but it is not working for me. The xdebug logs looks good, but not errors, nor warnings at all.

[18] Log opened at 2022-05-16 05:49:07.140566
[18] [Step Debug] INFO: Connecting to configured address/port: host.docker.internal:5902.
[18] [Step Debug] INFO: Connected to debugging client: host.docker.internal:5902 (through xdebug.client_host/xdebug.client_port). :-)
[18] [Step Debug] -> <init xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" fileuri="file:///var/www/html/webroot/info.php" language="PHP" xdebug:language_version="7.4.19" protocol_version="1.0" appid="18"><engine version="3.1.4"><![CDATA[Xdebug]]></engine><author><![CDATA[Derick Rethans]]></author><url><![CDATA[https://xdebug.org]]></url><copyright><![CDATA[Copyright (c) 2002-2022 by Derick Rethans]]></copyright></init>

[18] [Step Debug] <- feature_set -i 1 -n resolved_breakpoints -v 1
[18] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="feature_set" transaction_id="1" feature="resolved_breakpoints" success="1"></response>

[18] [Step Debug] <- feature_set -i 2 -n notify_ok -v 1
[18] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="feature_set" transaction_id="2" feature="notify_ok" success="1"></response>

[18] [Step Debug] <- feature_set -i 3 -n extended_properties -v 1
[18] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="feature_set" transaction_id="3" feature="extended_properties" success="1"></response>

For future reference... I thought the hostname line wasn't needed. This caused my php debugger's autoconfig to listen on :::5902 (i.e. IPv6) and thus wouldn't accept a connection from the docker IPv4 network.

I've followed all the steps as well, but it is not working for me. The xdebug logs looks good, but not errors, nor warnings at all.

[18] Log opened at 2022-05-16 05:49:07.140566
[18] [Step Debug] INFO: Connecting to configured address/port: host.docker.internal:5902.
[18] [Step Debug] INFO: Connected to debugging client: host.docker.internal:5902 (through xdebug.client_host/xdebug.client_port). :-)
[18] [Step Debug] -> <init xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" fileuri="file:///var/www/html/webroot/info.php" language="PHP" xdebug:language_version="7.4.19" protocol_version="1.0" appid="18"><engine version="3.1.4"><![CDATA[Xdebug]]></engine><author><![CDATA[Derick Rethans]]></author><url><![CDATA[https://xdebug.org]]></url><copyright><![CDATA[Copyright (c) 2002-2022 by Derick Rethans]]></copyright></init>

[18] [Step Debug] <- feature_set -i 1 -n resolved_breakpoints -v 1
[18] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="feature_set" transaction_id="1" feature="resolved_breakpoints" success="1"></response>

[18] [Step Debug] <- feature_set -i 2 -n notify_ok -v 1
[18] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="feature_set" transaction_id="2" feature="notify_ok" success="1"></response>

[18] [Step Debug] <- feature_set -i 3 -n extended_properties -v 1
[18] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="feature_set" transaction_id="3" feature="extended_properties" success="1"></response>

Increase the Xdebug loglevel to 10 (xdebug.log_level = 10). Then you see how it compares the file paths. Maybe your path mapping is misconfigured.

I'll leave this here for anyone that uses docker-compose.yml and can't get this to work.

So, for me, the Configure Windows Defender Firewall step wasn't necessary.

I only needed to add host.docker.internal:host-gateway as an extra_hosts to my service (docker-compose.yml) like this:

services:
  wordpress:
    build:
      context: .
      dockerfile: Dockerfile-wordpress # this is the filename of your Dockerfile
    extra_hosts:
      - "host.docker.internal:host-gateway"

and everything worked!
I found this here: https://blog.bitexpert.de/blog/win10_wsl2_docker_xdebug

Note: In my Dockerfile, I installed xdebug like this:

RUN pecl install xdebug \
    && docker-php-ext-enable xdebug