Using Xdebug 3.0 with PHPStorm


Yesterday was Xdebug 3.0 released:

Also what happened today was that I had to switch to a PHP 7.4 environment and use Xdebug, a combination I apparently hadn't used before. It turns out that Xdebug 3 is downloaded instead of the 2.X line. This caused my environment to stop responding to breakpoints I set in PHPStorm. These are the steps I followed to resolve the problem and get the PHP <-> Xdebug <-> PHPStorm combination going.

Change configuration

First up: PHPStorm. I updated it to the latest version (2020.2.4). I'm not sure if it is mandatory though.

Also, the default port of Xdebug changed from 9000 to 9003, so we need to change it. Go to Preferences -> PHP -> Debug and change the Debug port under the Xdebug section to 9003.

Next up: PHP configuration. You first have to find out where your current Xdebug configuration is located. You can find which configuration files are used by PHP using 2 methods:

  • Command-line: Run php --ini. This returns a list of all your configuration .ini files.
  • Brower: place <?php phpinfo(); in a .php file and open it. Search for these settings most likely somewhere at the top:

In my case (Valet Plus) my configuration was located in /usr/local/etc/valet-php/7.4/conf.d/z-performance.ini. Open the file and comment/remove the following lines:


Add these new settings:


Next: Restart PHP-fpm if required. How this works totally depends on your local environment but in the case of Laravel Valet (Plus) you can run this command: valet restart php.

If you receive this error you must enable the "Start listening for PHP Debug connections" setting:

Xdebug: [Step Debug] Could not connect to debugging client. Tried: localhost:9003 (through xdebug.client_host/xdebug.client_port) :-(

And that should be it. You can now run your PHP code and inspect all your variables when debugging code.

Manually updating Xdebug

When you regularly switch PHP versions, you might end up with a version with Xdebug 2.7.X installed and one version with Xdebug 3.0 installed. You can update Xdebug to the latest version by running this from the command line:

pecl upgrade xdebug

Extra tip

When breakpoints are not working, adding a call to xdebug_break(); in your code usually does. It's great to debug as it forces PHPStorm to stop, even though not all settings are correct. That way you know for sure that Xdebug is working.