Set up XDebug¶

XDebug is an extension for PHP that will help us with code debugging. We’ll use it combined with PHP Storm, which will provide us the step debugging feature, i.e. enable us to break during the code execution, inspect the variables in scope and evaluate code in the Console.

Install¶

sudo apt install php7.4-xdebug

Configure PHP¶

The congifuration to enable the debugger may not work on Ubuntu when added to php.ini. If debugging doesn’t work and the XDebug section of phpinfo says that the Step Debugger is disabled, try adding the configuration to the XDebug-specific configuration file. The file will have a name similar to 20-xdebug.ini. This file should appear in the printout of the command

php --ini

If there is no such configuration file, make sure that XDebug is enabled by running

sudo phpenmod -v ALL -s ALL xdebug

Configure XDebug on PhpStorm¶

Open Preferences/Languages and Frameworks/PHP.
Add your CLI interpreter here by opening CLI Interpreters window: inside it, click on plus sign and select Other Local…
Now you’ll need to adjust the PHP executable file path. If you’re unsure where your current PHP version executable file is, simply execute: which php and it will give you the path to the needed file.

If everything is done correctly, PhpStorm should now list your PHP version, XDebug as debugger and PHP configuration file, looking something like this:

PhpStorm XDebug config
Skip this step if using XDebug version 2 or below (default port on these versions is 9000 so no adjustment is needed).

Next, we need to adjust debug port to 9003 which is the default XDebug port. Do so by going to Preferences/Languages and Frameworks/PHP/Debug and setting Debug port under XDebug to 9003.
In the end we just need to start listening to debug connections: enable Run/Start Listening for PHP Debug Connections in the menu bar or use the shortcut button with the phone icon on the top right side of PhpStorm window.

Activating debugger¶

The easiest way for activating debugger is by installing XDebug Helper browser extensions. Choose your favorite browser, install and configure extension, and you’ll be able to start and stop debugging mode in your browser with just a few clicks. - XDebug Helper for Firefox - XDebug Helper for Chrome - XDebug Helper for Safari

Alternatively, if you want to activate the debugger manually, you’ll need to add a trigger to your requests. Depending on what you need, add one of the following: - XDEBUG_SESSION=session_name as an additional GET (or POST) parameter if you want to initiate debugging on that single request - XDEBUG_SESSION=session_name as a cookie: debugging will now be initiated as long as that cookie is present

(value of session_name here is not important, you can set it to whatever you like)

Test¶

Finally, choose a request you want to debug, set a breakpoint in PhpStorm on the line in your code you’re sure that your request will hit and fire away. If everything went well, PhpStorm should have opened debug window and now you have complete insight in what is happening in your code.

PhpStorm debug window

Easily enable and disable XDebug¶

To prevent XDebug slowing down our requests when we are not debugging, it would be wise to disable it whenever we’re not using it. That’s why we’ll guide you to write a few shell scripts and aliases with which XDebug enabling or disabling will be a matter of entering a three-letter command in terminal.

What we’ll want to do is rename xdebug.ini file so that it can’t be found and hence won’t be loaded, and after that reload PHP-FPM server. Again, as an example, everything will be done for PHP 7.4 so don’t forget to adjust commands to your version.

Ubuntu configuration¶

To enable XDebug on all PHP versions and SAPIs:

sudo phpenmod -v ALL -s ALL xdebug

To disable XDebug on all PHP versions and SAPIs:

sudo phpdismod -v ALL -s ALL xdebug

And reload fpm after that:

sudo systemctl reload php7.4-fpm