XDebug with Lando and PHPStorm on a Mac

Getting XDebug working with Lando using PHPStorm can be a bit of a journey as you piece together multiple blog posts and documentation from prior versions of Lando and PHPStorm. Here’s a step-by-step solution that works for me every time.

1. In the local lando config file (.lando.local.yml), add the following under config:

   webroot: [web]rnxdebug: true

   

2. Do a lando rebuild for the changes to take effect.
3. Add a /srv/includes/prepend.php file at the root of the repo (outside the web root). prepend.php will be just an empty file.
   
4. Add a server.
   1. In PHPStorm, go to Preferences > Languages & Frameworks > PHP > Servers.
   2. Click the + button.
   3. Give the server a name.
   4. Set Host to localhost and Port to 80/443 if using the .lndo.site url or the port number if using the localhost url. (Do lando info to get ports.)
   5. Set Debugger to Xdebug.
   6. Check the box for “Use path mappings.”
   7. Expand the files on the left to view the /srv/includes/prepend.php file you added and under “Absolute path on the server” column for the prepend.php file, add /srv/includes/prepend.php.
   8. Map the root by setting the root folder to /app. The value of /app can be found by doing lando ssh followed by pwd.
      
5. In Preferences > Languages & Frameworks > PHP > Debug, make sure the Xdebug: Debug port is listening on 9000 (for xdebug2) and 9003 for (xdebug3). So the textbox should be “9000,9003”.
6. Turn on debugging in PHPStorm.
7. Set a breakpoint.
8. Accept the connection request.
9. Walk through your code.

Stepping through your code with a debugger is a must-have when troubleshooting difficult issues. These steps should get you up and running without a ton of trial-and-error.