How do I set up Xdebug in PhpStorm with Laravel Sail Docker on WSL2 without Docker Desktop

Question

I am trying to debug Laravel Sail which is run via Docker on WSL2. I want to do this without Docker Desktop as this now requires a licence to use in a corporate setting.

I have been following this guide for setting this up

Debugging Laravel Sail with XDebug 3 in PHPStorm 2023: A Detailed Guide

The steps (short version)

1. Install Laravel Sail: composer require laravel/sail --dev && php artisan sail:install

2. Change/Add: SAIL_XDEBUG_CONFIG="client_host=host.docker.internal idekey=docker" to your .env file

3. Add PHP_IDE_CONFIG: "serverName=Docker" to your docker-compose.yml environment section of the laravel.test service

4. (Re-)Start your containers with ./vendor/bin/sail up -d

5. Add the new PHP Interpreter inside "PhpStorm -> Settings -> PHP" and choose the option “From Docker, Vagrant, …”

6. Adjust the network mode to your sail network name which you can get with docker network list

7. Change the Container path value of the interpreter from /opt/project to /var/www/html

8. In "PhpStorm -> Settings -> PHP -> Debug", change the port for Xdebug to 9003

9. In "PhpStorm -> Settings -> PHP -> Servers" add a new server for working with your test suite:

   • Name: Docker
   • Host: localhost
   • Port: APP_PORT from .env
   • Enable path mapping with the absolute path of the root directory to be var/www/html

10. In "PhpStorm -> Settings -> PHP -> Servers" add another server for intercepting web requests:

    • Name: 0.0.0.0
    • Host: 0.0.0.0
    • Port: 80
    • Enable path mapping with the absolute path of the root directory to be var/www/html

11. In "PhpStorm -> Settings -> PHP -> Test Frameworks" add a new remote interpreter with composer autoload path to /var/www/html/vendor/autoload.php

12. Apply all changes, enable the Debug connection listener and start debugging

I have enabled IPv4 in WSL as when I query the network I got an IPv6 network address from Windows machine for WSL Ethernet.

From WSL my network is:

**219df3435040**   `example-app_sail                    bridge    local`

3: br-219df3435040: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default
link/ether 02:42:97:4b:39:90 brd ff:ff:ff:ff:ff:ff
inet 172.20.0.1/16 brd 172.20.255.255 scope global br-219df3435040
valid_lft forever preferred_lft forever
inet6 fe80::42:97ff:fe4b:3990/64 scope link
valid_lft forever preferred_lft forever

I have changed the client_host=host.docker.internal to client_host=172.20.0.1

When I listen on PhpStorm I get the error in docker:

laravel.test-1 | WARN Xdebug: [Step Debug] Could not connect to debugging client. Tried: 172.20.0.1:9003 (through xdebug.client_host/xdebug.client_port)

I am also not sure if this line is correct on the guide as the serverName and idekey are different: SAIL_XDEBUG_CONFIG="client_host=host.docker.internal idekey=docker" to your .env file Add PHP_IDE_CONFIG: "serverName=Docker" to your docker-compose.yml

Answer 1

Thanks LazyOne for the info and everyone else that helped. It was really helpful to diagnose the issue. I installed wireshark to see if I could view the traffic on the wsl bridge network interface for the application. Turns out this is wrong in the guide mentioned. I noticed that there was no visible traffic except for pings? I then tried the eth0 interface ip to check for traffic and that worked. For the client_host I used my windows ip and it works. All the built in variables like client_host=host.docker.internal and xdebug://gateway totally threw me. The sail .env config I used to get this working is

SAIL_XDEBUG_MODE=develop,debug
SAIL_XDEBUG_CONFIG="client_host=192.168.1.219 discover_client_host=False idekey=DockerIDE"

I explicitly set the discover_client_host option as the auto discover was not working either.