Xdebug config for Lando running in WSL2 and PhpStorm running in Windows

xdebug.md

Xdebug

Note: This guide is for Lando running in WSL2 and IntelliJ IDEA (or PhpStorm) running in Windows 10+.

Most steps are from https://docs.lando.dev/guides/setup-lando-on-windows-with-wsl-2.html

Add these lines to ~/.bashrc inside WSL

# Set correct dev host to Windows
export LANDO_HOST_NAME_DEV=host.wsl.internal
export LANDO_HOST_GATEWAY_DEV=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2; exit;}')

Add these lines to ~/.lando/config.yml inside WSL

appEnv:
  LANDO_HOST_IP: $LANDO_HOST_NAME_DEV

Add these lines to .lando.yml

config:
  xdebug: true
services:
    appserver:
        overrides:
            extra_hosts:
                - ${LANDO_HOST_NAME_DEV:-host}:${LANDO_HOST_GATEWAY_DEV:-host-gateway}

Rebuild Lando project

lando rebuild -y

Restart WSL

In PowerShell:

wsl --terminate Ubuntu

Then open new WSL Terminal, and run lando start.

Install and activate browser extension

See https://www.jetbrains.com/help/phpstorm/browser-debugging-extensions.html

Activate IDE debugging

Run > Start Listening for PHP Debug Connections

Add breakpoint in IDE and refresh browser

IDE should break with this UI:

Select file matching the file path on server, and accept.

Now, in IDE, open Settings > PHP > Servers. Edit the localhost one and only map the "Project files" root to /app, like so:

/app/public may have been auto-mapped, you can empty its path field.

You should be good to go :)

Getting "Debug session was finished without being paused" for no reason?

In IDE: Go to Settings > PHP > Debug > Advanced settings, and uncheck Notify if debug session was finished without being paused.

Use Xdebug in PHP CLI script

# SSH into Lando
lando ssh

# Set Xdebug environment variables (make sure `serverName` matches your IDE server name)
export XDEBUG_MODE=debug XDEBUG_SESSION=1 PHP_IDE_CONFIG="serverName=localhost"

# Add your breakpoints and "Start Listening for PHP Debug Connections"

# Run your command (still in Lando shell)
php bin/console app:my:command

# IDE will break as usual

# Revert your environment variables
export XDEBUG_MODE=off XDEBUG_SESSION= PHP_IDE_CONFIG=

# Exit SSH
exit

Attention

Unfortunately the LANDO_HOST_GATEWAY_DEV won't be static, so if the IP address of WSL has changed, you need to do a lando rebuild to update the config.

One important additional step to include, so as to avoid banging your head against the wall, in the Windows Defender Firewall make sure to explicitly allow the port 9003 for inbound connections.

Me personally I've set the 9003 port open for incoming connections from anywhere, any protocol, all profiles, any program... because I've been banging my head for over a year now with this issue.