How to enable step debugging in PHP with Xdebug 3 and PHPStorm

Are you looking to debug your PHP code more efficiently? You can do this very easily with Xdebug 3 and PHPStorm. With this setup, you will be able to step through your code line by line, allowing for better visibility into how your program is executing and helping you identify any issues quickly. In this guide, I will show you how to enable step debugging in PHP with Xdebug 3 and PHPStorm.

These are the steps we're going to do to enable step debugging in PHPStorm:

1. Configure Xdebug 3
2. Configure PHPStorm
3. Testing it out

It's surprisingly simple to enable step debugging for PHP, so let's get started!

Configure Xdebug 3 to enable step debugging

The first step to enabling step debugging for PHP is to configure Xdebug 3. In this guide, I assume you've already installed PHP and Xdebug 3, so if you haven't, do so before continuing this process.

First, we'll need to find out which configuration we need to change to enable step debugging for Xdebug 3. An easy way to do this is by running an example PHP application, in my example Laravel, and placing phpinfo(); in the main script (public/index.php for Laravel). This shows a list of all loaded configurations in the "Additional .ini files parsed" section. Here you'll find a listing for Xdebug as well.

Usually, this is loaded from /etc/php/8.1/cli/conf.d/20-xdebug.ini. Of course the path depends on your PHP version and operating system. In my case, I'm running PHP 8.1 on Ubuntu, so yours might differ.

Find the path to your Xdebug configuration and open this in a text editor (or gedit, nano, vim) and change the contents of this file from:

zend_extension=xdebug.so

to

zend_extension=xdebug.so
xdebug.start_with_request=yes
xdebug.client_port=9003
xdebug.client_host=127.0.0.1
xdebug.mode=debug
xdebug.idekey=PHPSTORM

This configuration tells Xdebug to send information to port 9003 on your local machine. Now we'll configure PHPStorm to start an Xdebug client on port 9003.

Configure PHPStorm to enable step debugging

Now that we've configured Xdebug 3, we'll need to configure PHPStorm to receive debugging information from Xdebug. We'll need to set up an Xdebug Client inside PHPStorm. We can configure this by going to the PHPStorm settings: Ctrl + Alt + S. In the search bar, search for debug. You'll see the following screen:

In the Xdebug section, be sure that the Debug port is set to port 9003, and the Can accept external connection option is checked. Press "Apply" and "OK". Now you're ready to test your step debugging!

Test the step debugging with Xdebug 3 and PHPStorm

You've configured Xdebug 3 and PHPStorm, so now it's time to test your new debugging abilities! Run your PHP development server (php artisan serve for Laravel), place a breakpoint in your code, and Start Listening for PHP Debug Connections:

Once you've started listening, you can go to your application in the browser and you should get a notification in PHPStorm. You will need to select the project to assign the notification to, but after that, you'll get nice breakpoints in PHPStorm:

You can now place breakpoints anywhere and start debugging your PHP applications like a programming ninja!

Conclusion

With the help of Xdebug 3 and PHPStorm, you can now debug your code like a pro. You'll be able to quickly identify any issues that may arise in your applications with ease. With a few simple steps, I've shown you how to configure step debugging for PHP so that you can save time and energy when developing complex projects. As long as you follow these instructions, it should only take minutes before start seeing great results from using this powerful toolset!