- 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
First, the proper docs, which you should refer to before my own 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.
Check environment in PHP service
env | grep XDEBUG
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
idekeyis often 'phpstorm' but may only need to be set?
serverNameis 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
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.
- https://gist.github.com/xurizaemon/4b30f525b555c4c2399cac7bdfe08ad5 is a CLI Lando config with xdebug enabled