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¶

MacPorts install¶

MacPorts provide multiple ports for installing XDebug, based on the PHP version you’re using. So, to check your version, execute on the command line:

php -v

and select the appropriate port from the list found here.

For example, if your PHP version is 7.4, you’ll need to execute

sudo port install php74-xdebug

Now, when executing

php -v

among other data, you should see XDebug in the output. Just by this setup you already have some XDebug benefits, such as that var_dump() function will now be upgraded to have a nicer output. But to fully benefit XDebug, it is wise to add few more adjustments to configure step debugging and connect it to PhpStorm.

Configure PHP¶

Depending on XDebug version you’re configuring, add the following lines to php.ini: - XDebug3 and higher

xdebug.mode=debug,develop

XDebug2 or under:

xdebug.remote_enable=1
xdebug.default_enable=0
xdebug.profiler_enable=0
xdebug.auto_trace=0
xdebug.coverage_enable=0

If you’re not sure which php.ini file to edit, you can check that by executing

php --ini

Make sure you restart PHP-FPM server after making these changes. If you followed this development setup, then reload commands should look something like this on Mac:

sudo port reload php74-fpm

or like this on Ubuntu:

sudo systemctl reload php7.4-fpm

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.

MacOS configuration¶

Execute the following in the console:

cd /usr/local/bin
sudo vim disable-xdebug-74.sh

In the Vim editor, paste the following code:

#!/usr/bin/env bash

mv /opt/local/var/db/php74/xdebug.ini /opt/local/var/db/php74/xdebug.ini.disabled
port reload php74-fpm
echo "xdebug is now disabled"

Save and exit Vim.

We just created our script for disabling XDebug. Let’s also create a one for enabling it. Execute:

sudo vim enable-xdebug-74.sh

Here, paste:

#!/usr/bin/env bash

mv /opt/local/var/db/php74/xdebug.ini.disabled /opt/local/var/db/php74/xdebug.ini
port reload php74-fpm
echo "xdebug is now enabled"

and again, save and exit. After doing this, you should be able to enable and disable XDebug by executing one of the commands:

sudo sh /usr/local/bin/enable-xdebug-74.sh
sudo sh /usr/local/bin/disable-xdebug-74.sh

To make this even more simple, you can also create aliases for these commands. To do this, execute:

cd ~
vim .zshrc

Add the following lines to your .zshrc file:

alias exd74='sudo sh /usr/local/bin/enable-xdebug-74.sh'
alias dxd74='sudo sh /usr/local/bin/disable-xdebug-74.sh'

(exd74 and exd74 here can be any other alias you like: feel free to use what suits you best)

By doing this, you can now enable XDebug simply by executing exd74 and disable it by executing dxd74.