When a Lando, PHPStorm, and XDebug setup gets hairy | Untold Studio Skip to main content
Untold Studio Untold Studio

Main navigation

  • About
  • Work
  • Blog
  • Handbook
  • Menu
  • Contact
  • About
  • Work
  • Blog
  • Handbook
Email Us
hello@untoldhq.com
Visit Us
P.O. Box 16391
Portland, OR 97292
Follow Us
Twitter LinkedIn
← back to blog

When a Lando, PHPStorm, and XDebug setup gets hairy

It's early in the weekday. You take a sip of coffee at work and hit refresh. PHPStorm breakpoints aren't catching anymore. You destroy and rebuild Lando to no avail. How could it have suddenly stopped working? Let's sleuth this together.

Did you RTFM like the Lando folks have asked?

Kevin McConnaughay
Kevin McConnaughay

I mean… yeah, sure. I definitely will.

Mike Purvis
Mike Purvis

You swear you didn't do anything. Your Lando + PHPStorm + XDebug was working yesterday and now it's not. Let's realize that we're dealing with a few different components that may not always play well together.

#1 We're using the Lando Drupal 8 recipe

By the way, the docs for Lando mention the recipes and which ones are available. For those interested in the nitty gritty, you can find the details in Github.

At the time of this writing, some of those files were updated a couple months ago.

#2 PHPStorm is always updating

While the folks at Jetbrains are super on it, I believe the settings can get imported incorrectly and you have to tear your hair out to get things right. Pro tip: there's a thing called Jetbrains Toolbox which lets you have multiple versions of an app. 

I'll spare the lengthy philosophical discussion on "how to live your best debugger life" but certainly a chapter would be, "slowly eliminate could-be's." It "could-be" my version of PHPStorm? Use Jetbrains Toolbox and find out. Wasn't that? Move on to eliminating the next suspect. 🕵️

#3 Docker Desktop is also updating

We ran into an issue where an .env file was automatically picked up and parsed for environment variables. This wasn't happening with earlier versions of Docker Desktop. So there's another variable to throw into the mix.




So don't beat yourself up if these three (and more) stop playing nicely. We can get it back into balance, even if it's ugly and hairy. Here I'll cover an odd case that I haven't found elsewhere online.

First off, one of the best resources for getting Lando, PHPStorm, and XDebug working is the video and content on this page.

However, PHPStorm might not automatically detect XDebug or stop automatically detecting it. If you follow this video and under "CLI Interpreters" you see "Debugger: Not installed" check this out.

This is problematic:

Notice that upon expanding the "Configuration file" list, xdebug is not listed. Weird.

This is odd, seeing as the .lando.yml file has: xdebug: true

Let's dive into the container using lando ssh

Quick detour:

Are we actually ssh'ing into our container? That's debatable, but like the Lando command says, we're dropping "into a shell on a service." Feels very much like ssh'ing. What's going on behind the scenes? I feel like I'm trusting Lando with everything and feel lost! If you're familiar with regular Docker commands, this is essentially running docker exec:

docker exec -it <container_id> bash

Try it yourself by getting the container id for php-fpm via docker ps Or instead of trusting me, check out their Github ssh task that calls their Lando engine, which is aliased to docker exec.

Neat, we're learning and demystifying stuff.

End of detour, back on track.

Once you're in the shell you'll see that the …xdebug.ini file is there after all. So let's spit out the contents of that file:

Copy the path to the xdebug.so file and plop that into the "Debugger extension" then click the icon to refresh:

For good measure, patiently watch that entire video linked above again and don't skip steps.

Lastly, if you're still having issues with XDebug and aren't seeing any errors, try including a custom php.ini file that'll set XDebug logging up. That can help catch errors and guide your StackOverflow searching.

name: untold-drupal
recipe: drupal8
config:
  webroot: web
  via: nginx
  database: mariadb
  xdebug: true
  config:
    # here's our custom php.ini file
    php: .lando.php.ini
services:
  appserver:
    overrides:
      environment:
        # support debugging Drush with XDEBUG.
        PHP_IDE_CONFIG: "serverName=appserver"
  database:
    # So you can reliably use this port to see the database
    portforward: 3307

The .lando.php.ini contains:

xdebug.remote_log = ./xdebug.log

I hope this will help folks in a tangle and elucidate what's going on behind the scenes with ever-changing Lando, PHPStorm, and XDebug.

Tags
lando
drupal
phpstorm
xdebug
Mike Purvis
Mike Purvis
Lead Developer
You might find this post useful:
Engineering the Untold Website