Skip to main content
Ungathered Thoughts

XDebug, Lando and a CLI service

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.


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

Check environment in PHP service

Config to check

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.

More links