"

Debugging with Xdebug and PHPStorm

This site uses Lando’s pantheon recipe. Getting Xdebug and PHPStorm to talk to each-other is a bit different for the pantheon recipe than for the drupal8 recipe. The instructions here should work for both Drupal’s front-end (i.e.: from a web browser) and CLI scripts (i.e.: drush, behat).

Last tested on 2021-08-04 with Lando v3.1.4, PhpStorm 2021.2, PHP 7.4.16, Xdebug v3.0.4 running on Linux 5.11.0-25 / Ubuntu 21.04 hirsute.

Set up Lando

1. Add or inspect a .lando.local.yml at the root of the repo, and add this if it’s missing.

    config:
      xdebug: true

2. Run lando rebuild -y to re-create the appserver with xdebug enabled, and the new environment variables set.

Set up PHPStorm

  1. Run lando php --version and note the major PHP version (e.g.: 7.3)
  2. Go to Settings -> PHP (i.e.: the root of the PHP settings). Set the following:
    1. PHP language level = (set to the major PHP version)
    2. CLI Interpreter = <no interpreter>
    3. Include path:
      1. Remove all other paths if they exist.
      2. Add ~/.lando/config/pantheon
    4. Click “Apply” to save your changes.
  3. Go to Settings -> PHP -> Servers

    1. Remove other servers if they exist

    2. Add a new server:

      1. Name = appserver
      2. Host = settlenet.lndo.site (or whatever lando rebuild gives you), port = 80, debugger = Xdebug
      3. Check Use path mappings
      4. Add the following mappings. If the Pantheon path isn’t there, navigate to File -> Open…, open that path, and attach it to the current session. (You should be able to add the entry then.)
        File / Directory Absolute path on the server
        $path_to_repo /app
        ~/.lando/config/pantheon /srv/includes

    3. Click “Apply” and/or “OK” to save your changes.

  4. Go to the Run menu -> Edit configuration:
    1. Click “+” to add a Run/Debug configuration, and choose “PHP Web Page”:
      1. Name = settlenet
      2. Server = appserver
      3. HTTPS = (check)
      4. Start URL = /
    2. Click “Apply” and/or “OK” to save your changes.

Debugging

  1. When you’re ready to start debugging, then:
    1. Make sure you have a breakpoint set,
    2. Make sure breakpoints aren’t muted,
    3. Make sure PHPStorm is not listening for [arbitrary] debug connections (Run menu -> “Stop Listening for PHP Debug Connections” - if you see “Start Listening…” then it’s turned off) - the next step will tell PHPStorm to only listen for Xdebug connections from the settlenet appserver.
  2. Go to Run -> Debug ‘settlenet’. A Debug pane will appear. The icon beside “settlenet” should have a little green dot in the bottom-right to indicate it is actively listening.
  3. This should automatically load the front page with debugging enabled. Note the ?XDEBUG_SESSION_START=NNNNN (where NNNNN is an arbitrary number, usually 5 digits), or copy it to a temporary file on your workstation.
  4. Navigate in the tab that PHPStorm started to the page you want to trigger the breakpoint on. Or, if you want to use a different browser or container, navigate to the page, then paste the ?XDEBUG_SESSION_START=NNNNN you noted earlier and press Enter to reload the page. If applicable, do whatever you need to do in order to trigger the breakpoint (e.g.: submit a form, start a batch process, etc.).