Debugging Drupal 8 with PHPstorm and Lando on your Mac

Selwyn Polit // February 2019

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.

TL;DR

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. xdebug.remote_port=9001); 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 Drupal instance.  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 127.0.0.1 (localhost).  It looks a little like this.

Here port 9002 is being listened to by Phpstorm and port 9000 by php-fpm.

3. A slightly more technical version:

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

 

What exactly could this be?

$ lsof -i TCP:9000
COMMAND   PID    USER      FD    TYPE                        DEVICE SIZE/OFF NODE NAME
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; it is pretty simple.  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: site
recipe: drupal8
config:
  webroot: docroot
  php: 7.2
  xdebug: true
  config:
    php: .lando.php.ini
tooling:
  drush:
    service: appserver
    cmd: drush —root=/app/docroot

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
xdebug.remote_port=9002

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 below.

Some Chrome magic

Make sure you have the xdebug helper extension installed in Chrome

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.

The debug cookie looks like this:

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

Congratulations!

Click Accept and you’ll notice you are debugging:

Troubleshooting

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 172.20.0.1:9000.
W: Creating socket for '172.20.0.1:9000', poll success, but error: Operation now in progress (29).
E: Could not connect to client. :-(
Log closed at 2019-02-08 16:31:05

Versions

$ lando version
v3.0.0-rc.7

Mac OSx High Sierra
10.13.6

PhpStorm 2018.3

Credits

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

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

 

Partnered Content

This article was originally published by Isoveran Selwyn Polit on his personal blog.