Debugging Drupal8 with PHPstorm and Lando on your Mac

By Selwyn Polit, 25 August, 2021


When you use homebrew to install php 7.1 it will cleverly install php-fpm which listens on port 9000.  This is the default port for xdebug, so if you want to debug php scripts in a lando container, you will have some challenges.


If you've installed php 7.1 with homebrew, it listens on port 9000 so you will need to change the containers php.ini port specification to another port.  e.g.


Then tell phpstorm to listen on port 9001


Get a Fresh Drupal 8 instance running with Lando

If you need to, I suggest following the wise instructions of my buddy Benji Fisher to install a fresh instance of Drupal.  Make sure it is running in your browser.

Who is listening?

Only one program can listen on a port at a time.  If a program is already listening on the port that you want to use for debugging, it won't work.

There are several ways to check if a program is listening on port 9000 (the default port for xdebug).

1. In terminal, you can type:

nc -z localhost 9000

if it says:

Connection to localhost port 9000 [tcp/cslistener] succeeded!

Something is listening.  If you get nothing, then nothing is listening. No need to change any ports.


2. You can run network utility, scan port 9000 to 9003 on (localhost).  It looks a little like this.  Here port 9002 is being listened to by Phpstorm and port 9000 by php-fpm.


Network Utility

3. A slightly more technical version:

$ netstat -an | grep 9000
tcp4       0      0         *.*                    LISTEN    

What exactly could this be?
$ lsof -i TCP:9000
php-fpm 732 selwyn    7u  IPv4 0x4120ed57a07e871f      0t0  TCP localhost:cslistener (LISTEN)
php-fpm 764 selwyn    8u  IPv4 0x4120ed57a07e871f      0t0  TCP localhost:cslistener (LISTEN)
php-fpm 765 selwyn    8u  IPv4 0x4120ed57a07e871f      0t0  TCP localhost:cslistener (LISTEN)


Lando settings

Here is my .lando.yml file.  There are some really important parts highlighted in yellow.  xdebug: true tells Lando to configure the php in the container to enable xdebug.  The php: .lando.php.ini tells Lando to use a custom config file to override some of the php settings.

name: mysite
recipe: drupal8
  webroot: docroot
  php: 7.2
  xdebug: true
    php: .lando.php.ini
    service: appserver
    cmd: drush --root=/app/docroot


Lando D8 php.ini file

Some php.ini magic

In order to satisfy the section of the .lando.yml file with this line: php: .lando.php.ini,  you will want to create a file called .lando.php.ini in the root of your project.  Mine looks like this:

xdebug.remote_enable = 1
xdebug.remote_autostart = 1

Notice the xdebug.remote_port.  This tells the php to send it's debug info via port 9002 instead of it's default of port 9000.

Settings in Phpstorm

Look at settings in phpstorm, Languages and frameworks, PHP, Debug and change the port to 9002 to match the setting in the .lando.php.ini file above.

PHPStorm XDEBUG preferences

Some Chrome magic

Make sure you have the xdebug helper extension installed in Chrome

Xdebug Helper



Final steps to debugging

Set a breakpoint in the code in phpstorm (or add a line xdebug_break();)  Here I've added a breakpoint in index.php (the red dot in the middle of the page.)


Tell phpstorm to start listening by clicking the green telephone in the toolbar.  (View toolbar to turn on the toolbar.)  It is clicked already in the image above.

Now click the green bug in chrome.  This causes Chrome to send a debug cookie.

Click Debug


The debug cookie looks like this:

debug cookie

Refresh the page in Chrome (any page from your site) and you should see Phpstorm pop up a scary looking dialog:

phpstorm incoming debug dialog



Click Accept and you'll notice you are debugging:

You are debugging



Navigate to /admin/reports/status/php which will tell you the php settings and confirm that:

xdebug.remote_port is set to 9002.  If it is set to 9000, Phpstorm will never see any requests and you will be frustrated.


I found it super useful to enable xdebug logging in the .lando.php.ini file like this.  I was then able to browse the contents of the xdebug.log file to watch what was happening.  The xdebug.log file is created in the root of the project.

xdebug.remote_log = ./xdebug.log


The clue was :9000 indicating port 9000 and the fact that it could not connect to client.

Log opened at 2019-02-08 16:31:05
I: Checking remote connect back address.

I: Checking header HTTP_X_FORWARDED_FOR.
I: Remote address found, connecting to
W: Creating socket for, poll success, but error: Operation now in progress (29).
E: Could not connect to client. :-(
Log closed at 2019-02-08 16:31:05



$ lando version

Mac OSx High Sierra

PhpStorm 2018.3



Check out some of the following useful links for more:



Thanks to Eugene at Jetbrains tech support for helping me get to the root of this!

Thanks to the brilliant Benji Fisher at Isovera for his many contributions!

Thanks to Tim Jensen for helping me dig into Xdebug after hearing my pleas for help on the Lando slack channel.