Over the past few months, I've been test-driving various Docker-based local development environments with two goals in mind. First, as my "daily driver" for consulting work - I've been a long-time MAMP Pro user and I've been feeling for a long time that I need to modernize my local development tools. Second, I'm trying to figure out what is the most ideal local development environment for students of both our 12-week Drupal Career Online class (starts March 19) and our 6-week Mastering Professional Drupal Development Workflows with Pantheon (starts February 26) courses. 

One of the necessary skills for a professional Drupal developer (one who codes either modules or themes) is to be able run a solid debugging tool. As part of my evaluation of Lando, I decided to figure out how to set up local PHP debugging with Xdebug and PhpStorm on Mac OS X.

This process described below is largely based on a comment in an issue thread in the Lando issue queue by David Hunt - thanks, David!

My local setup includes:

• Mac OS X Sierra 10.12.6  
• Lando v3.0.0-beta.21  
• Google Chrome with the Xdebug helper extension 
• PhpStorm 2016.1.1  

Starting point

This tutorial assumes that you have a local Drupal site up-and-running in Lando and set up as a project in PhpStorm. In this example, my local site is using the Lando "Pantheon" recipe, but as you'll see in a bit, any recipe can be used. Also - my local site is based on the standard Drupal project composer template (with a nested docroot).

Enable Xdebug in Lando

The first step is to enable Xdebug in Lando - this is easily done by modifying the local site's .lando.yml file. In my case, I added the following:
 

If your .lando.yml file is defining a custom appserver service, then you should be able to just add the "xdebug: true" bit to the appserver definition. 

Once added, you'll need to perform a "lando rebuild" - this will rebuild your environment based on your .lando.yml, including adding Xdebug. The documentation page for the "rebuild" command includes a caution about how there's no guarantee that data will persist between rebuilds. In my experience, I haven't had any issues with losing my database. If you're concerned, then you may want to perform a "lando db-export" prior to rebuilding.  

Configuring PhpStorm

Here's where some magic comes in. Admittedly, I don't fully understand the details of some of the configuration necessary in PhpStorm to get debugging working, but I can confirm that following these steps, it has worked every time for me so far.

The first step is to add the Lando recipe folder as an "Include path" in your PhpStorm project. Open Preferences > Languages & Frameworks > PHP, click the "+" button at the bottom of the list, and manually type in the name of the folder of the Lando recipe you're using. On my machine it is: /Users/michael/.lando/services/config/pantheon. If you're using the standard "Drupal8" recipe, then it would be: /Users/michael/.lando/services/config/drupal8. Unless your username is also "michael", you'll want to update the path.
 

Then, go to Preferences > Languages & Frameworks > PHP > Servers

If no server for your project exists (it might be called “appserver”), then enable PhpStorm to listen for Xdebug connections, load a page from your local site in your browser and PhpStorm will prompt you to accept the incoming connection. In my case, it didn’t matter if the Xdebug helper is set to debugging or disabled at this point.
 

Then, once a server for your local site exists (remember, it might be called "appserver”), select it and ensure that "Use path mappings" is checked, and ensure that your project folder is mapped to "/app" for the "Absolute path on server". Also ensure that the "Absolute path for the server" for the “include path” is "/srv/includes".

Give it a try!

At this point, we should be ready for debugging! As a test, open up the site's index.php in PhpStorm and place a breakpoint.

Then, using the Xdebug Helper extension, enable debugging. Also ensure that PhpStorm is still set to listen to incoming Xdebug connections. 

Finally, load your local site's home and watch how PhpStorm will pause code execution at your breakpoint in the index.php file.
 

Warning - performance will suffer

While Xdebug is a powerful tool and will absolutely save you loads of time, there's a dark side. Performance will suffer. I recommend disabling Xdebug in your .lando.yml - by setting "xdebug: false" - (and rebuilding) when you're not using it. You can leave it enabled and gain back some (but not all) performance by disabling PhpStorm's listener as well. 

Final thoughts

In case you're wondering where some of the configuration settings come from, here's what I've figured out so far:

• "appserver" is the name of the Lando service that contains the codebase. 
• "/app" is the absolute path of the codebase in the "appserver" Docker container. 
• "/srv/includes" is the absolute path to a Lando-provided "prepend.php" file in the "appserver" Docker container. As far as I can tell, this file defines and sets a bunch of environment variables depending on the recipe used.