• Published:
  • Under: Development

 

Lando, PhpStorm, Drupal and Xdebug

The question I get asked most often when discussing my Lando development environment with other Drupal Web Developers is, "How do you setup Lando and PhpStorm to debug Drupal using Xdebug?" This blog post will help you do exactly that.

Before you start, you should have a Drupal website up-and-running in Lando. Even a freshly-installed, blank Drupal website will do.

Once you finish, you will be able to use PhpStorm to:

  • Debug Drupal 8 (and 7) in Lando: a Docker-based development environment
  • Debug drush commands for Drupal in Lando
  • Debug phpunit tests for Drupal in Lando
    • because if you had just written your unit test before you wrote that snazzy method, like you were supposed to...😉

Tested using:

 

  • OSX
    • v10.12.6
    • v10.13.6
  • PhpStorm v2018.2.2
  • Xdebug v2.6.1
  • Lando v3.0.0-beta.47
  • Docker v18.06.1-ce-mac73 (26764)
  • Drupal
    • v8.6.0
    • v7.59
  • drush v8.1.17
    • NOTE: drush 9 is currently NOT supported in PhpStorm 
  • phpunit 
    • v6.5.12 for Drupal 8 
    • v6.5.3 for Drupal 7

Prerequisites:

Prepare your Drupal in Lando for PhpStorm: 

Imag1

Create a custom php.ini for your Drupal in Lando website: 

In the root directory of your lando project, create a "config" directory. 

  • For example, on OSX this might be: ~/Sites/yourdrupal.lndo.site/config/

Inside this config directory, create a php.ini file with the following:

Imag2

Edit the .lando.yml file for your Drupal in Lando website:

Add the following to the "config" key of the .lando.yml file, so that Lando will include your new php.ini.  

Image 3

Add the following to the "services" key of the .lando.yml file, so that Lando will include a PHP_IDE_CONFIG for PhpStorm.

Image 4

Change "yourdrupal.lndo.site" above to match the domain name of your Drupal in Lando website.

Add the following to the "tooling" key of the .lando.yml file, so Lando will recognize "lando phpunit" commands.

If Drupal 8: 

Image 5

Change "web" above to match the webroot directory of your Drupal 8 in Lando website.

If Drupal 7: 

Image 6

Examples of complete Drupal 8 and Drupal 7 .lando.yml files:

A complete but basic Drupal 8 .lando.yml configured for PhpStorm would look like the following:

Image 7

A complete but basic Drupal 7 .lando.yml configured for PhpStorm would look like the following:

Image 8

In fact, you could use either of the above .lando.yml files as written, just to test things out. If you plan on spinning-up both of them on the same machine at the same time, though, change the value in "name:" and "PHP_IDE_CONFIG:" of at least one of them first. 😉

Rebuild your Drupal in Lando website in order to apply the new settings.

Image 9

 

Create a new PhpStorm Project for your Drupal in Lando website:

Open PhpStorm and click on the following:

File > New Project from Existing Files

  • Source Files are in a local directory, no Web server is yet configured
  • Click on the “Next” button.
Image 11

Mark as Project Root a directory to create the project 

  • Click on "Project Root" 
    • (in the top left window toolbar.) 
  • Select your drupal root directory.
    • For example, 
      /Users/You/Sites/yourdrupal.lndo.site/web

      Last, Click on the “Finish” button.

Image 11_2

 

Enable Drupal Support:

After the project finishes indexing, the Event log window should be visible. If it isn’t, click on "Event log" in the bottom-right of the screen.

In the Event log window, enable the suggested items by clicking on them:

  • Enable the Symfony Plugin with auto congiguration now
    • (may or may not be available) 
  • Enable Drupal Support, which should display the "Enable Drupal Integration" configuration window below. 

Enable Drupal Support:

  • Verify that "Enable Drupal Integration" is checked. 
  • Drupal installation path: (Select your drupal root directory)
    • For example, 
      /Users/You/Sites/yourdrupal.lndo.site/web
  • Verify that "set up PHP | Include paths" is checked
  • Version: 8
    • (or whatever Drupal version you are using) 
  • OK
Image12

The above configurations can also be set at:

  • PhpStorm > Preferences > Languages & Frameworks > PHP > Frameworks

If prompted by the Event log window, “Set Drupal-style formatting for this project”.

Configure your PhpStorm project:

 

Setup the PHP Interpreter for the project:

  • PhpStorm > Preferences > Languages & Frameworks > PHP
  • PHP language level: 7.1
    • (or whatever PHP version your Drupal in Lando website uses).
  • Click on the "..." icon to the right of the "CLI Interpreter" field.
Image13

In the window that opens, 

  • control+n
    • (or click on the "+" icon at the top left of the pane.) 
  • Select "From Docker..." 
Image15
  • Server: Docker
  • Image Name: devwithlando/php:7.1-apache
    • (or whatever PHP version your Drupal in Lando website uses)
  • PHP interpreter path = php
  • OK
Image15_2
  • Apply
  • OK
  • Apply
Image16

Setup the PHP Server for the project:

  • PhpStorm > Preferences > Languages & Frameworks > PHP > Servers
  • Click on the "+" in the top left of the left pane.
  • Name: yourdrupal.lndo.site
    • (Change this to match the domain name of your Drupal in Lando website.
  • Host: yourdrupal.lndo.site
    • (Change this to match the domain name of your Drupal in Lando website.)
  • Port: 80
    • (or whatever lando provided, if applicable)
  • Debugger: Xdebug
  • Enable: "Use path mappings"

 

Set the path mapping for the Drupal in Lando website's root directory:

In the "File/Directory" column, highlight the (path to your Drupal root) row that is listed under the "Project files" folder, by clicking on it.

  • For example, click on: 
    /Users/You/Sites/yourdrupal.lndo.site/web
  • Edit the "Absolute path on the server" field for the highlighted row.
    • Click on the highlighted edit icon that is visible on the right of the same row
    • Type: 
      /app/web
    • Press the enter key to update the field.
  • Apply
Image16_2

Set the path mapping for drush in Lando:

 

If Drupal 8: 

In the "File/Directory" column, highlight the (path to your included drush) row that is listed the under the "Include path" folder, by clicking on it:

  • For example, click on: /Users/You/Sites/yourdrupal.lndo.site/web/vendor/drush/drush
  • Edit the "Absolute path on the server" field for the highlighted row.
    • Click on the highlighted edit icon that is visible on the right of the same row
    • Type: /usr/local/bin/drush
    • Press the enter key to update the field.
  • Apply:
Image17

If Drupal 7:

In Terminal, add a symlink at your Drupal web root to your globally-installed drush

  • For example, on OSX:
Image18

In PhpStorm, highlight your newly created "drush" symlink row that is listed the under the "Include path" folder, by clicking on it.

  • Edit the "Absolute path on the server" field for the highlighted row. 
    • Click on the highlighted edit icon that is visible on the right of the same row.
    • Type: /usr/local/bin/drush
    • Press the enter key to update the field.
  • Apply
Image18

Configure PhpStorm to debug browser-triggered events for your Drupal in Lando website:

  • PhpStorm > Preferences > Languages & Frameworks > PHP > Debug
  • External Connections
    • Enable “Break at first line in PHP scripts”
      • (to at least verify that the debug session is working)
    • Max simultaneous connections = 19
      • Press the tab key to update the field.
  • Apply
Image19

Configure PhpStorm to debug "lando drush" commands for your Drupal in Lando website

  • PhpStorm > Preferences > Tools > Command Line Tool Support
  • control+n
    • (or click on the “+” icon on the left side of the main pane)
Image20
  • Select "Custom tool" (not "Drush") from the dropdown menu.
    • We don't select "Drush" here because the path to the Lando appserver's drush must be entered manually.
21
  • Visibility = project
  • OK
22
  • Set the path to the Lando appserver's drush: 
/usr/local/bin/drush

Alias

drush
  • OK
23
  • Show console in: tool window 
  • Apply
  • OK 

24

 

Test your Drupal in Lando PhpStorm Debugging Setup:

 

Start listening for PHP debug connections: 

  • command+shift+L in PHPStorm

In your web browser, reload your Drupal in Lando website. You do NOT need an Xdebug Helper browser extension for this to work. With the above settings, PhpStorm will automatically pause your website at:

  • If Drupal 8: line 14 ("$autoloader) of index.php
  • If Drupal 7:  line 17 ("define") of index.php

Note: PhpStorm did NOT automatically focus the PhpStorm application in your computer display. With the current PhpStorm settings, you have to switch to PhpStorm manually in order to see that it is pausing your website. We will change this setting in the next step.

fn+command+F2 to stop debugging but continue listening for PHP Debug Connections

To focus PhpStorm automatically when a breakpoint is set:

  • PhpStorm > Preferences > Languages & Frameworks > PHP > Debug > External connections
  • Uncheck "Break at first line in PHP scripts".
  • Apply
  • OK
24

Test browser-triggered debugging:

 

If Drupal 8: 

  • Add a breakpoint at line 14 ("$autoloader") of web/index.php
  • Add a breakpoint at line 236 ("function user_load") of web/core/modules/user/user.module

If Drupal 7:

  • Add a breakpoint at line 19 ("require_once") of web/index.php
  • Add a breakpoint at line 365 ("function user_load") of web/core/modules/user/user.module

In your web browser, navigate to yourdrupal.lndo.site/user/1

  • Focus will switch to PhpStorm and catch at the breakpoint in index.php.
  • fn+F9 to jump to the next breakpoint.
  • PhpStorm will catch at the breakpoint in user.module.
  • fn+command+F2 to stop debugging but continue listening for PHP Debug Connections

Test "lando drush" debugging:

In Terminal:

24
  • PhpStorm will catch at the breakpoint that is still set for user.module in the example above.
  • fn+command+F2 to stop debugging but continue listening for PHP Debug Connections

 

Test phpunit debugging:

 

If Drupal 8:

  • Add a breakpoint at line 62 ("$this->password") of web/core/tests/Drupal/Tests/Core/Password/PasswordHashingTest.php
  • Run a phpunit test in Terminal:

25

  • Focus will switch to PhpStorm and catch at the breakpoint in PasswordHashingTest.php.
  • fn+command+F2 to stop debugging but continue listening for PHP Debug Connections
    • You may have to fn+command+F2 more than once

If Drupal 7:

  • Enable the Testing module:
26
  • Remove the breakpoint you set above at line 365 ("function user_load") of web/core/modules/user/user.module
  • Add a breakpoint at line 23 ("require_once") of web/modules/simpletest/tests/password.test
  • Run a phpunit test in Terminal:

27

  • Focus will switch to PhpStorm and catch at the breakpoint in password.test
  • fn+command+F2 to stop debugging but continue listening for PHP Debug Connections
    • You may have to fn+command+F2 more than once

 

Happy Drupal in Lando debugging with PhpStorm!

28

Have your own tricks for Drupal debugging? Share your thoughts with us on Twitter, and subscribe to our newsletter for more content like this!