For me one of the most important factors for efficient local development is the ability to quickly toggle Xdebug on or off. In this guide I will show you how to configure Xdebug for Lando and PhpStorm.
Lando’s documentation instructs you to enable xdebug via the .lando.yml file. As of Lando RC2 you must set
xdebug: true in order for the Xdebug extension to be loaded in your container. However, by default Xdebug will trigger on each request, which is not what we want because it makes local development painfully slow.
For more granular control it is better to configure Xdebug via php.ini, which should contain these lines:
xdebug.remote_enable = 1 xdebug.remote_autostart = 0 xdebug.remote_connect_back = 1 html_errors = 1
The first line tells Xdebug to try to connect to the IDE (i.e., PhpStorm), which will only happen if two conditions are met (see below). The second line tells Xdebug not to start debugging automatically; we want to control when Xdebug starts rather than have it run on every request. The third line tells Xdebug to try to connect to whichever client (i.e., your browser) that made the HTTP request. This setting is particularly important for reliable debugging with Nginx servers. The last line is not essential, but it’s nice to see error messages formatted in HTML instead of plain text.
Add this to .lando.yml in order to load the php.ini file:
config: config: php: php.ini
For anyone interested, here is my Lando WordPress configuration.
PhpStorm Debug Configuration
Configuring PhpStorm debug settings is actually fairly straightforward.
Click on Edit Configurations to open the Run/Debug Configurations dialog box. Choose the PHP Web Page option.
Give the configuration a name, such as Lando. Next click the … to add a server.
Configure a new server named appserver with a host of
Check the box for path mapping and map the project root to Lando’s app root, usually
Click OK to save the settings.
If everything is configured correctly you are ready to debug. As I mentioned earlier there are two conditions that must be met in order to begin debugging.
When you refresh your browser with these two settings enabled Xdebug will be activated. Make sure you have a breakpoint set in order to pause execution. The easiest way to toggle Xdebug is via the browser extension. Once you are finished, disable debugging from the browser extension and set PhpStorm to stop listening for Xdebug connections.
You may also debug command line scripts such as phpunit. Triggering Xdebug for command line scripts is slightly different because we cannot use the browser extension. Instead we must set environmental variables.
- Set PhpStorm to start listening for Xdebug connections (same as above)
- SSH into the container:
- Set the XDEBUG_CONFIG environmental variable:
export XDEBUG_CONFIG="remote_enable=1 remote_host=$LANDO_HOST_IP"
- Set the PHP_IDE_CONFIG environmental variable:
export PHP_IDE_CONFIG="serverName=appserver". Note the name “appserver” must match the server name set under PhpStorm’s debug configuration.
- Run the CLI script inside the container.
As always, logging is a big help when debugging any piece of software, and Xdebug is no exception. You can enable logging by adding
xdebug.remote_log = "./xdebug.log" to the php.ini, which is particularly helpful when debugging fails for no apparent reason.
Mac users should find Selwyn Polit’s post helpful for fixing issues related to port availability.
The article Setting up Xdebug with Lando and PhpStorm as well as the comments were helpful in figuring out the settings that I’ve described here. Also, many thanks to the Lando developers for building what I consider to be the best local development environment and for providing excellent support for the software.