XDebug, Lando and a CLI service

I use Lando to simplify management of my local development environments.
I use PHPStorm to edit, comprehend and debug complex PHP codebases.
I use XDebug as a debug tool

If you've not discovered how helpful XDebug can be when debugging PHP, I strongly recommend you give it a try. If you don't code in PHP, find the equivalent tooling!

The initial setup for XDebug can be complex as a number of things have to be aligned to function correctly. A challenge for me is that when I try to configure it I've typically just run into a gnarly problem on a project; once I get it running my monkey brain turns straight back to debugging and forgets to record what steps I took to configure the debugger. Over time I'd collected a scattered set of "today, x worked" notes in my lab journal. This Saturday morning, a person asked in the Lando Slack asked how to get it running, and I figured I'd document a few details that often catch me out.

How does XDebug work?

A quick outline works as I understand it.

When PHP starts executing something, if the XDebug extension is loaded then it can be activated
XDebug and a debug client (your IDE, etc) may then communicate
XDebug will connect to the configured IDE via IP and port
The IDE will decide whether to handle this request
The IDE can tell XDebug about breakpoints in code

Docs

First, the proper docs, which you should refer to before my own notes.

My notes

Check XDebug module is enabled

lando ssh then php -i | grep -i xdebug - you'll see XDebug's configuration from PHP config here

Environment variables Lando sets

Among other variables, Lando sets these when XDebug is enabled for a service.
- XDEBUG_MODE
- XDEBUG_CONFIG,
- PHP_IDE_CONFIG
- PHP_IDE_KEY

Check environment in PHP service

lando ssh then env | grep XDEBUG
Check XDEBUG_MODE and XDEBUG_CONFIG

Config to check

client_host - should point at the IP of the host the IDE is running on
discover_client_host - can use HTTP headers to discover the IP of the browser and connect to IDE on that IP address
idekey is often 'phpstorm' but may only need to be set?
serverName is the XDebug server name passed to PHPStorm

Config to check - IDE

XDebug will pass the file path and other execution information to the IDE. The IDE needs to know which paths correspond from your IDE OS and the environment it's running in. PHPStorm has a settings screen (Settings > PHP > Servers) where you can map the project's files to the path as seen within the environment XDebug runs in. Here I've set the project root to map to /app in Lando.
![[attachments/Pasted image 20230610152023.png]]

XDebug on a CLI only Lando

Lando service configuration

If PHP is running on another service than "appserver", the global Lando configuration option may not be applied. (I think this is here.) If you want XDebug on a service not named "appserver", the global xdebug option won't apply and you should set xdebug: on the service instead.

Lando restart after switching networks

Lando's XDEBUG_CONFIG variable won't update if your laptop switches IPs until you restart. This can mean that XDebug stops working after you move locations. lando restart -y should refresh the IP of the Lando service you want to debug.