Configuring xDebug from docker4drupal for Drupal 8

Hello everyone!

It's been a while since I've written anything here, and today I thought it was a good time to do it. Because yes, sometimes things should not be overthought, because we get into a flow of procrastination that we don't want.

After several personal events that have happened since that June 7 that I wrote my last article, it's time to talk about Drupal. Because if you are here reading it is not for the love of art, right?

These months I've been working "full throttle" with docker4drupal, a wonderful stack of docker utilities specifically for Drupal; very similar to ddev, another acclaimed stack which I've also had to use in some projects. Docker4drupal is wonderful, as it allows you to use, almost at the click of a button, a wide variety of containers already prepared just to be enabled, through the docker-compose.yml.

In this article we are not going to dwell too much on what docker4drupal is and what it offers; we are going to be much more specific. We will talk about how to enable and configure xDebug in docker4drupal.

As you know, xDebug is the PHP extension that allows the developer to debug code. It is a must-have if you are developing in Drupal, so it is almost mandatory to have it enabled and running in our favorite IDE, PHPStorm.

Configuring docker-compose.yml

Enabling xDebug in docker4drupal has no science or many more mysteries than those described in some other work of Jesus Relinque, in fact the Wodby team has left it very well documented. We must also clarify that, since version 3 of xDebug, the configuration has improved a lot, and now it is easier than ever to enable xDebug, so don't wait any longer to upgrade!

The first step will be to configure our docker-compose.yml file, which will be the docker-compose.override.yml if we already have a Drupal project up and running. We will add the following configuration directives:

PHP_XDEBUG: 1
PHP_XDEBUG_MODE: debug
PHP_XDEBUG_REMOTE_HOST: 127.0.0.1
PHP_XDEBUG_DEFAULT_ENABLE: 1
PHP_XDEBUG_START_WITH_REQUEST: "yes"

After this, we are going to recreate the containers for the changes to take effect.

docker-compose up -d

Now we will check from the php.ini if we already have the xDebug extension enabled. We can check this directly from our Drupal, in the following path:

/admin/reports/status/php

Configuring PhpStorm

There is one last step to be able to debug our elegant and organized code; configure our IDE, PhpStorm.

To do this, we will click on the "Add Configuration" button, which appears at the top right of the IDE. Then we will add a PHP Web Page configuration. Now we proceed to create a server that listens for web requests; to do this we click on the 3 dots "..." and then on the "+".

We fill in the fields, including the host (the dns provided by docker4drupal to access our site) and the listening port of the site, which is usually 8000 or 80. The last step to have our server ready, is to map the paths, so we check both the "User path mappings..." check and the "Shared" check, and we map some paths (it is not necessary all of them) taking into account that the local path of our project must match the web server that has virtualized docker with the php service/container. For example, the root path of our project, would normally be mapped to /var/www/html.

Final steps and troubleshooting

We only have to test that everything works (sometimes, the hardest step...)

From PhpStorm, we will place a breakpoint in some code block which we are sure will be requested when accessing via web in our site. If at startup we observe that it does NOT work, pay attention to the errors or log warnings that we get from the IDE and try sequentially the solutions that I propose:

1. Dumbest mistake: Are you sure the block of code you set the breakpoint(s) for is being requested? I suggest that you put more breakpoints, in a hook that you know is going to be launched from a contrib module or from the Drupal core itself.
2. The most computer error: restart and maybe it will work. Now seriously, it seems silly, but try restarting PhpStorm and stopping (make stop) and raising the containers again (make up). The cache is real.
3. Launch drush commands from the shell (for example, a drush cr) and check if you get any xDebug logs; If so, it is a good sign.
4. If none of the above has worked, it's not your lucky day. You can try downloading the xDebug extension available for the browser, which makes things easier.
5. If you have come this far, it is because you have possibly gotten confused in some step, you have a different version than the one explained in this post, or you are not a true Drupal Jedi. Keep reading the conclusion.

Conclusion

You know I always like to end with a conclusion. And xDebug is about healing your health and peace of mind. Drupal health authorities do not recommend excessive use of print_r() and echo in code debugging; Please visit xDebug to make your life easier :)