Xdebug is an indispensable PHP debugging and profiling extension. Xdebug 3 works with PHP 8.4 and integrates seamlessly with VS Code, PhpStorm, and other IDEs for step-through debugging, stack traces, and code coverage. This guide installs and configures Xdebug 3 on Ubuntu 26.04 LTS.

Tested and valid on:

  • Ubuntu 26.04 LTS

Prerequisites

  • Ubuntu 26.04 LTS with PHP 8.4 installed
  • An IDE that supports Xdebug (VS Code with PHP Debug extension, PhpStorm)
  • A development environment (not for production use)

Step 1 – Install Xdebug

sudo apt install php8.4-xdebug -y

Step 2 – Locate the Xdebug Extension

php -m | grep -i xdebug
php --ini | grep xdebug

Step 3 – Configure Xdebug for Step Debugging

Edit the Xdebug config file (usually auto-created):

sudo nano /etc/php/8.4/mods-available/xdebug.ini

Add:

zend_extension=xdebug.so
[xdebug]
xdebug.mode = debug
xdebug.start_with_request = yes
xdebug.client_host = 127.0.0.1
xdebug.client_port = 9003
xdebug.log = /var/log/xdebug.log

Step 4 – Enable for CLI and FPM

sudo phpenmod -s cli xdebug
sudo phpenmod -s fpm xdebug
sudo systemctl restart php8.4-fpm

Step 5 – Verify Xdebug is Active

php -m | grep -i xdebug
php -r 'var_dump(xdebug_info());'

Step 6 – Configure VS Code

Install the PHP Debug extension by Xdebug. Create .vscode/launch.json:

{
    "version": "0.2.0",
    "configurations": [{
        "name": "Listen for Xdebug",
        "type": "php",
        "request": "launch",
        "port": 9003,
        "pathMappings": {
            "/var/www/myapp": "${workspaceFolder}"
        }
    }]
}

Step 7 – Profile PHP Performance

Set Xdebug to profiling mode to find bottlenecks:

xdebug.mode = profile
xdebug.output_dir = /tmp/xdebug

Open the resulting cachegrind.out.* files with KCachegrind.

Conclusion

Xdebug 3 is configured for PHP 8.4 on Ubuntu 26.04 LTS. Use step debugging to set breakpoints and inspect variables, code coverage to test your PHPUnit suites, and profiling to identify performance bottlenecks.