Debugging Drupal 9 with Xdebug and (VSCode || PHPStorm)

In the old days, debugging Drupal websites consisted of printing out an array variable and inspect its values within. However, today with a more complex Drupal codebase, those days are gone and ... behold Xdebug

Xdebug emerged as a nicer tool for debugging Drupal 9 sites when developing modules or themes. Therefore, In this post will be configuring Xdebug with Lando and integrating with VSCode as well as PHPStorm.

Drupal 9 configuration

Let's start with the Drupal 9 configuration, we will be using the Composer drupal/recommended-project.

Thus we will spin off a new Drupal 9 site like so:

$ composer create-project drupal/recommended-project my_site_name_dir

Composer will take care of the third-party dependencies and downloading Drupal core files, just change the my_site_name_dir for the name of your project.

Lando configuration

We will be using the drupal9 recipe for lando which already come with a LAMP-based system for running Drupal 9 sites. This recipe is using PHP 7.3 per default. However, we will be running PHP 7.4 so we can use the latest version from the time of writing this post.

Here is my Lando (.lando.yml) file:

name: laboratory
recipe: drupal9
config:
  webroot: web
  php: 7.4
  xdebug: true
  config:
    php: ./php.ini

Here is a Gist for .lando.yml file: esnaremaussa/.lando.yml

xdebug: true

With this option, Lando will include Xdebug in the Docker container.

php: ./php.ini

This option will allow us to tell Lando to use our own php.ini configuration rather than using the default php.ini file.

php.ini configuration

This is the php.ini you should include in your project:

; Xdebug
xdebug.max_nesting_level = 256
xdebug.show_exception_trace = 0
xdebug.collect_params = 0
xdebug.remote_enable = 1
xdebug.remote_autostart = 1
xdebug.remote_host = ${LANDO_HOST_IP}
xdebug.remote_log = ./xdebug.log
xdebug.remote_port = 9000

This is a Gist for the php.ini file esnaremaussa/php.ini

This is a very generic configuration for Xdebug and everything should work out of the box after running lando start. Nevertheless, these two configuration items are very important, especially when experiencing problems with Xdebug:

xdebug.remote_port = 9000

Xdebug will be listening on port 9000 per default. Nevertheless, if you run into issues with Xdebug, don't' hesitate to change the port to 9001 (or anything, really) and rebuild lando.

xdebug.remote_log = ./xdebug.log

The xdebug.remote_log flag is used for defining the location of the Xdebug logs. Very handy when things don't work as expected.

The name can be anything and be located anywhere within your working directory. Right now, as configured above, the xdebug.log file will be located at the root of the application.

Trust me, changing the port when experiencing problems with Xdebug may just fix all your problems and save you a lot of time wandering around.

Wrapping up (first part)

Up to this point, you should be able to run lando start and have a Drupal 9 site up and running with Xdebug listening on port 9000.

For the second part, we will be configuring the most popular IDEs among PHP developers, VSCode and PHPStorm.

Xdebug and VSCode

Configuring VSCode with Xdebug is very simple, all you have to do is following these steps:

Make sure have installed the PHP Debug plugin.
This plugin can be found here: PHP Debug.
Create the folder .vscode in the root of your application and create the launch.json file with the following code:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for XDebug",
      "type": "php",
      "request": "launch",
      "port": 9000,
      "log": true,
      "pathMappings": {
        "/app/": "${workspaceFolder}/"
      }
    }
  ]
}

Note: in the port section, make sure is the same port added in the php.ini file.
This is a Gist for the launch.json file esnaremaussa/launch.json

Create breakpoints on your code.
For testing purposes, you can go to the index.php file and add $test = 1 and add that line as a breakpoint in VSCode.
Go to the debugger section on VSCode and run the option which says: Listen for XDebug.
Finally, go to your Lando site and refresh your browser.

You should end up seeing something like this:

NOTE: On the Breakpoint section (bottom left in the image above), Everything is marked as default. You should uncheck all the breakpoints selected per default and only leave the ones you have marked in your code.
For some reason, the default breakpoints do not work with Drupal.

PHP Storm and Xdebug

Let's breakdown the PHPStorm configuration is a series of steps:

Open the configuration window.
You can get there by clicking on: configuration -> Languages and Frameworks -> PHP
On PHP language level, we tell PHPStorm that we will be using PHP 7.4
Let's configure the CLI Interpreter.

NOTE: You will have to tell to PHPStorm the path of the Xdebug.so file, you can get that by running these commands:
$ lando ssh
$ cat /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini

Now, create some breakpoints and start listening for Xdebug connections.
Refresh your browser and the debugger will show up with the index.php variables.

Up to this point, you should have a functional PHPStorm + Xdebug configuration. Nevertheless, there is more to it, you can have Drush, PHP Unit and more integrations with PHPStorm.

I will add a couple of links at the end of the post where there will be more info about

Have fun and debug away!

More Resources

https://docs.lando.dev/guides/lando-phpstorm.html
https://docs.lando.dev/guides/lando-with-vscode.html
https://untoldhq.com/blog/2019/08/02/when-lando-phpstorm-and-xdebug-setup-gets-hairy

Blog