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 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 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. 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
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 above.
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
References
Check out some of the following useful links for more:
- Jetbrains howto article on Phpstorm debugging and Docker
- Mike Anello doing some tricky Drupal 8, Xdebug and Lando magic
- Tim Jensen gets down and dirty with Xdebug and Lando
- The Lando official version of using Drupal 8, Xdebug and Lando (on Linux)
Credits
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.