Debugging Drupal 9 with Xdebug and (VSCode || PHPStorm) 
Tags: xdebug, drupal, vscode, phpstorm
Published: 2020-09-06 06:09:23

[![Alt Text](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/i2yx44fd0btopp8lkmpp.png)](https://www.buymeacoffee.com/Esnare)
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](https://github.com/xdebug/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](#xdebug-and-vscode) as well as [PHPStorm](#php-storm-and-xdebug).

## Drupal 9 configuration
Let's start with the Drupal 9 configuration, we will be using the Composer [drupal/recommended-project](https://github.com/drupal/recommended-project). 

Thus we will spin off a new Drupal 9 site like so:
```bash
$ 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](https://docs.lando.dev/config/drupal9.html) 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:

```yml
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](https://gist.github.com/esnaremaussa/7328289a49fbdd628ed9f2a3e965d8d3)

### 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:

```ini
; 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](https://gist.github.com/esnaremaussa/7328289a49fbdd628ed9f2a3e965d8d3)

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:

1. Make sure have installed the PHP Debug plugin.
This plugin can be found here: [PHP Debug] (https://marketplace.visualstudio.com/items?itemName=felixfbecker.php-debug).

2. Create the folder **.vscode** in the root of your application and create the **launch.json** file with the following code:

```json
{
  "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](https://gist.github.com/esnaremaussa/7328289a49fbdd628ed9f2a3e965d8d3)

3. 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.

4. Go to the debugger section on VSCode and run the option which says: **Listen for XDebug**.

5. Finally, go to your Lando site and refresh your browser.

You should end up seeing something like this:
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/q7j45ta3xlvsxgc3itsh.png)

> 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:

1. Open the configuration window.
You can get there by clicking on: configuration -> Languages and Frameworks -> PHP
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/oywlx1r5qoxqikrmsiep.png)

2. On PHP language level, we tell PHPStorm that we will be using PHP 7.4
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/4a3ygy6sv5gag4j3zduw.png)

3. Let's configure the CLI Interpreter.
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/ybr4gqnmxlsvgi21qso1.gif)

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

4. Now, create some breakpoints and start listening for Xdebug connections.
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/1b7rqhboa1wzb39fsm51.png)

5. Refresh your browser and the debugger will show up with the **index.php** variables.
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/p97zeleiynvig5bkmpfc.png)



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