Debug your XDebug: Advanced Troubleshooting part 2— Settings

The first part of this article discussed how to check and resolve network issues when XDebug won’t work with your IDE. This part is about debugging XDebug issues when XDebug are correct and network communication between it and IDE is up and working.

When PHP interpreter with installed XDebug is asked to debug your code it should start XDebug which informs IDE about the begin of debugging session. If this doesn’t happen the typical reason is that PHP wasn’t triggered to start XDebug. But firstly we have to check if PHP interpreter can work at all with XDebug. From XDebug host execute command:

$ php -a -dxdebug.start_with_request=yes

Which gives you PHP prompt with working XDebug . If something went wrong it will print you some error, then check XDebug settings again and fix them as described in the Part 1.

In my case it works:

$ php -a -dxdebug.start_with_request=yes
Interactive shell
php >

Now feed PHP prompt with some valid PHP, for example:

php > echo 1;
Xdebug: [Step Debug] Could not connect to debugging client. Tried: 172.17.0.1:9000 (through xdebug.client_host/xdebug.client_port) :-(

Uh-oh, it gave you an error! Well, don’t worry, it is because we haven’t started XDebug client on IDE host side. As in the article Part 1 for testing we will use XDebug command line client called dbgpClient so let’s start it on the IDE host:

$ ./dbgpClient
Xdebug Simple DBGp client (0.4)
Copyright 2019–2020 by Derick Rethans
In dumb client mode
Waiting for debug server to connect on port 9000.

Now when I try to input some PHP into prompt I get no errors on PHP and XDebug side and this on IDE side:

$ ./dbgpClient
Xdebug Simple DBGp client (0.4)
Copyright 2019–2020 by Derick Rethans
In dumb client mode
Waiting for debug server to connect on port 9000.
Connect from 172.18.0.6:35066
DBGp/1.0: Xdebug 3.0.1 — For PHP 7.4.13
Debugging file:///var/www/html/php shell code (ID: 43/PHPSTORM)

PHP execution now is in stopped state because it waits for commands from dbgpClient (or from IDE if you have started it). Using dbgpClient you can even ontrol debugging session manually by commands like run, step_into and many others, the full list is in dbgpClient manual.

Now, when we tested that XDebug works with PHP-shell can communicate with dbgpClient it’s time to find why XDebug won’t start when PHP execute a script that you try to debug whenever it is a command line script or a site page using PHP. As is mentioned at the article begin this usually happens when PHP-interpreter wasn’t triggered to start XDebug. The trigger methods are described in XDebug documentation and in short words for command-line PHP scripts it is present of XDEBUG_SESSION environment variable and for browser it is XDEBUG_SESSION parameter in HTTP-request or HTTP-cookie with the same name (or use a browser extension that set required triggers). There are also alternative ways to trigger it:

• setting xdebug.start_with_request config parameter to “yes” (XDebug starts at the begin of executing of any PHP-code)
• setting xdebug.start_upon_error config parameter (XDebug starts on error)
• calling xdebug_break() function from your PHP-code.

When things get more complicated and issues with XDebug are unclear even after the investigation that was made above, it is very helpful to use XDebug logging where every XDebug action can be seen and which can be turned on with xdebug.remote_log parameter in XDebug settings or from command line parameter:

php -a -dxdebug.log=/tmp/xdebug.log -dxdebug.start_with_request=yes

So, now we know how to solve almost any XDebug setup problem whether it is a network connection issue or XDebug incorrect settings. Having XDebug up and working we get much richer and deeper insight into PHP code internals and as a result can find bugs easier and faster. Happy coding!