Upgrade to xdebug 3

I changed my working laptop a few days ago, and had to rebuild all the development docker images. After that, I could no longer debug web pages with XDebug from PHPStorm.

In my dev Dockerfile, xdebug was installed from PECL, and at some point, the version installe by default was upgraded to xdebug 3, without me knowing that. Luckily, I was aware that new xdebug has breakign changes, and soon realized that I needed to updated some settings. Diving into details of the new xdebug settings is out of scope of this post, for that please refer to the upgrade guide. Here, I will point out a couple of moments that were of practical use for me.

Turns out, the default setting for xdebug.mode is develop, which doesn’t trigger debug sessions even if XDEBUG_SESSION_START request entry or XDEBUG_SESSION cookie are present. In order to enable step by step debugging in web environment, you have to add debug or trigger to xdebug.mode, so it becomes, for example, develop,debug. Also, I didn’t first pay attention to the fact that you can only change this setting in php.ini, and not in .htaccess or .user.ini (also, the setting can be overriden by environment variable XDEBUG_MODE, but that’s something I learned later).

I added xdebug.mode=develop,debug to my xdebug.ini, also I had to change xdebug.remote_host to xdebug.client_host. I use this setting because in development environment we use Docker, and xdebug is unable to discover client IP address automatically, so I set it manually to my LAN IP address:

xdebug.client_host=192.168.X.X

With this settings, I was able to debug web pages again. Hope that helps someone.

UPDATE from 25.12.2020: And I have just noticed this in Xdebug documentation:

A select set of settings can be set through an XDEBUG_CONFIG environment variable. In this situation, the xdebug. part should be dropped from the setting name. An example of this is: export XDEBUG_CONFIG="client_host=192.168.42.34 log=/tmp/xdebug.log"