Install xdebug for web and CLI

What is xdebug

Xdebug is a PHP extension that enables profiling and step debugging.

It is very useful for debugging issues, and provides a more reliable way to trace your code, as apposed to just using dd() or var_dump().

Xdebug can be used with the cli, web and APIs, but it needs to be configured to do that, most guides just cover the web, but the aim of this guide is to help cover all platforms.

Installation on macos

This guide assumes that you have PHP already installed, if you didn't you can simply run brew install php and afterwards run php -v to verify it is installed.

if your device is using apple silicon (m1) run:

arch -arm64 sudo pecl install xdebug

otherwise run:

pecl install xdebug

Installation on ubuntu/debian

Run sudo apt-get install php-xdebug this will install xdebug for the latest version of PHP, you can specify the php version in this format sudo apt-get install php7.4-xdebug

Configure xdebug

Now that xdebug is installed, we're going to need to configure it so it runs, first run php -v you should see something like the following:

PHP 8.0.8 (cli) (built: Oct 26 2021 11:42:42) ( NTS )
Copyright (c) The PHP Group
Zend Engine v4.0.8, Copyright (c) Zend Technologies
    with Zend OPcache v8.0.8, Copyright (c), by Zend Technologies
    with Xdebug v3.0.3, Copyright (c) 2002-2021, by Derick Rethans

This verifies that xdebug is installed, now we need to locate the ini file to configure it, run php --ini, this will show you all ini files that are loaded, look for this section

Loaded Configuration File:         /etc/php/8.0/cli/php.ini

This is the ini file we need to configure, open this file with your preferred text editor

code /etc/php/8.0/cli/php.ini

on macos you should see zend_extension=xdebug.so on the top of the file, if not, you can add it.

finally add these values, the idekey parameter is dependant on your preferred IDE, if you're using PHP Storm, then use PHPSTORM

[xdebug]
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.idekey=vscode

And finally use that same idekey for setting an environment variable, you need to add this line to your .bashrc or .zshrc file, which can be located at ~/.bashrc or ~/.zshrc.

export XDEBUG_CONFIG="idekey=vscode"

Now all we need to do is restart nginx, and php

ubuntu

sudo service nginx restart
sudo service php-fpm restart

Macos

brew services restart php
brew services restart nginx

if you're using Laravel Valet you should also run sudo valet restart

Configure IDE

Now that xdebug is installed correctly, we just need to configure our IDE to use it, if you're using vscode, install this plugin, and on PHP Storm, everything you need is already there.

Xdebug 3.x uses port 9003 instead of 9000 on xdebug 2.x, so make sure to account for that while setting your ide, the vscode plugin already accounts for that, and on phpstorm consult this section

Once configured you should be able to debug cli scripts, but there's one final step needed to get this running on web and API calls.

For web, install this plugin on your web browser and edit the idekey in it to match the idekey you set in the php.ini file

And to activate xdebug in API calls in your favorite REST client, you can either add this query parameter to your request's uri

https://yoursite.com/api/endpoint?XDEBUG_SESSION_START=vscode

this value is your idekey, and once your hit your API with a breakpoint set in your IDE it will activate step debugging.

The other way is to add a cookie to your request that contains that same parameter.

Finally, place a breakpoint in your code, and listen for xdebug in your IDE, in vscode just hit f5 and on phstorm, click on the phone icon on the top right, and run your code.