Xdebug is an indispensible tool when working on PHP projects. It's a very powerful debugger which can be used for code coverage when running tests as well.

Assuming you have installed the latest stable PHP version using Homebrew, you should use pecl to install the Xdebug. Pecl is a repository for PHP extensions. First, make sure you have it installed (even though it comes with the Homebrew PHP version).

which pecl

/usr/local/bin/pecl

Try to install Xdebug:

pecl install xdebug

That can be done in two ways: your installation passes, and you get a message like this:

Successful installation

...

Build process completed successfully
Installing '/usr/local/Cellar/php@7.4/7.4.16/pecl/20200930/xdebug.so'
install ok: channel://pecl.php.net/xdebug-3.0.4
Extension xdebug enabled in php.ini

In this case, all you need to check is whether PHP has linked the module correctly.

php -v

PHP 7.4.16 (cli) (built: Mar  4 2021 20:52:51) ( NTS )
Copyright (c) The PHP Group
Zend Engine v3.4.0, Copyright (c) Zend Technologies
    with Zend OPcache v7.4.16, Copyright (c), by Zend Technologies
    with Xdebug v3.0.4, Copyright (c) 2002-2021, by Derick Rethans

If you get an error message, you'll need to find your php.ini file.

php --ini

Configuration File (php.ini) Path: /usr/local/etc/php/7.4
Loaded Configuration File:         /usr/local/etc/php/7.4/php.ini
Scan for additional .ini files in: /usr/local/etc/php/7.4/conf.d
Additional .ini files parsed:      /usr/local/etc/php/7.4/conf.d/error_log.ini,
/usr/local/etc/php/7.4/conf.d/ext-blackfire.ini,
/usr/local/etc/php/7.4/conf.d/ext-opcache.ini,
/usr/local/etc/php/7.4/conf.d/php-memory-limits.ini

Go to /usr/local/etc/php/7.4/php.ini and edit it by adding

[xdebug]
zend_extension="xdebug.so"
xdebug.mode=debug,develop
xdebug.client_port=9003

at the end of the php.ini file.

That's it, you're ready to go.

Unsuccessful installation

When installing Xdebug, you might get the following error:

Build process completed successfully
Installing '/usr/local/Cellar/php@7.4/7.4.16/pecl/20200930/xdebug.so'

Warning: mkdir(): File exists in System.php on line 294
PHP Warning:  mkdir(): File exists in /usr/local/Cellar/php/7.4.16/share/php/pear/System.php on line 294

Warning: mkdir(): File exists in /usr/local/Cellar/php/7.4.16/share/php/pear/System.php on line 294
ERROR: failed to mkdir /usr/local/Cellar/php/7.4.16/pecl/20180731

Go to your PHP installation folder (/usr/local/Cellar/php/7.4.16/, for instance) and type

ls -all

total 168
-rw-r--r--   1 infinum-denis  staff   3.1K Aug  7 10:10 INSTALL_RECEIPT.json
-rw-r--r--   1 infinum-denis  staff   3.1K Jul  3 13:30 LICENSE
-rw-r--r--   1 infinum-denis  staff    64K Jul  3 13:30 NEWS
-rw-r--r--   1 infinum-denis  staff   1.6K Jul  3 13:30 README.md
drwxr-xr-x  12 infinum-denis  staff   384B Aug  7 10:10 bin
-rw-r--r--   1 infinum-denis  staff   628B Aug  7 10:10 homebrew.mxcl.php.plist
drwxr-xr-x   3 infinum-denis  staff    96B Jul  3 13:30 include
drwxr-xr-x   4 infinum-denis  staff   128B Jul  3 13:30 lib
lrwxr-xr-x   1 infinum-denis  staff    23B Aug  7 10:10 pecl -> /usr/local/lib/php/pecl
drwxr-xr-x   3 infinum-denis  staff    96B Jul  3 13:30 sbin
drwxr-xr-x   4 infinum-denis  staff   128B Jul  3 13:30 share

You can see that pecl is symlinked to /usr/local/lib/php/pecl, but which pecl specified /usr/local/bin/pecl, which is itself a symlink to /usr/local/Cellar/php/7.4.16/bin/pecl. Therefore, you need to remove the symlink.

unlink pecl

Now you can install Xdebug again, and it should work as described in the previous case (follow the steps described above to add it correctly into your php.ini).

Possible side effects

A possible side effect of running Xdebug, especially if you enable profiler output in Xdebug settings in php.ini, is that the file can grow very large. To prevent this, just make sure you delete it every once in a while, or simply don't enable logging.

Using Xdebug

You can use Xdebug to debug your CLI scripts (tests for instance), or debug your web application.

In order to debug the web application, you'll need a browser extension. In Chrome it's Xdebug helper, in FF it's Xdebug helper for Firefox.

If you are using PhpStorm, setting up Xdebug is straightforward. In VSCode you'll need to install the PHP Debug extension, configre it, and then you should be able to set breakpoints in your code.

Be sure to enable the helper and listener in your IDE.

Debugging CLI scripts

When you want to debug the CLI scripts, such as automated tests or custom commands, you need to add a manual trigger:

XDEBUG_TRIGGER=yes CLI SCRIPT

This will instruct Xdebug to be triggered on the script run.

WSL2 issues

Windows Subsystem for Linux (WSL) works differently than MacOS system, because you need to set the correct external IP address for Xdebug to be able to 'listen' to the requests.

To quickly find the external IP of your WSL you can type

ip route show default | awk '{print }'

in your WSL terminal. Then you need to add this IP address as your xdebug.client_host in your php.ini or xdebug.ini settings.

After that make sure you restart your PHP server. You should be able to use XDebug normally.

In order to debug the CLI scripts, you'll need to add additional environment variable

XDEBUG_TRIGGER=yes PHP_IDE_CONFIG=serverName=yourprojectname.test CLI SCRIPT

PhpStorm

For webserver script debugging (e.g. integration test debugging), you can add the URL to your server setup, and correct port mappings in the server settings, and it should work.

In the case of running script debugging that isn't tied to a specific domain (for instance you want to debug a phpcs sniff), the server name can be localhost, but it's important to correctly set up path mappings. For instance in the image below

The name of the server is WSL, host is localhost, but the port mappings between the local files and server files are specified (note that the local ones have \\wsl$ prefix, while the server ones are the ones you get by typing pwd inside your terminal, like /home/...).

Then running the script as

XDEBUG_TRIGGER=yes PHP_IDE_CONFIG=serverName=WSL CLI SCRIPT

Will correctly trigger a breakpoint and you can debug your script as before.

That is because from the PhpStorm's point of view, the WSL distribution is a server, so it needs to have the correct port mappings available so that it can connect the dots.

Visual Studio Code

Install the PHP Debug extension published by Xdebug. The PHP Debug extension can also be found in VSCode's Extensions tab by searching for it.

Once installed click on the Run tab and select "Add configuration...". Now, you'll need to pick the PHP environment. A new launch.json file will be added to the root directory by VSCode. By default it will contain 3 configurations. The one you need is the "Listen for Xdebug".

Example of the "Listen for Xdebug" configuration:

{
    "name": "Listen for Xdebug",
    "type": "php",
    "request": "launch",
    "port": 9003
}

Start debugging by opening the debug mode tab. In the dropdown select "Listen for Xdebug" and click the green debug button next to the dropdown.

If the process started successfully you will now see several options in the window, via which you can pick what logs Xdebugger will show like:

• Notices
• Warnings
• Errors
• Exceptions
• Everything

And you will see a small floating bar where you can Pause/Stop the debugger or step trough the steps when debugging breakpoints.

While the debugger is running you can run unit tests or run your website (chrome php debug extension needed) and debugger will listen for anything you selected and show you the data in the VS Code debug view.

Using Xdebug in Postman

There are some instances where you'd like to debug the logic for your API calls.

In this case you'll need to add a query parameter to your endpoint URL:

https://yoururl.test/wp-json/wp/v2/posts?XDEBUG_SESSION_START=PHPSTORM

The query parameter value can be changed according to your IDE.