Debugging in PHP with Xdebug11
24

Xdebug is a powerful debugging and profiling tool for PHP that helps us analyze and optimize PHP applications. It supports features such as step-by-step debugging, performance measurement, and stack tracing, which makes debugging much easier and provides better insight into the code. Below is a small setup guide for using it within VSCode.

---

Install Xdebug

We install Xdebug on a current Ubuntu system as an example:

sudo apt-get install -y php8.4-xdebug

Finally, we create a temporary directory for later storage of profiling and tracing data:

mkdir -p /tmp/xdebug

Configuring Xdebug

After installation, we configure Xdebug. To do this, we edit the en/php.ini:

vi /etc/php/8.4/fpm/conf.d/custom.ini

A useful basic configuration follows:

[xdebug]
; mode (see: https://xdebug.org/docs/all_settings#mode)
;   reasonable default
xdebug.mode=debug,profile
;   disabled
;xdebug.mode=off
;   step debugging
;xdebug.mode=debug
;   performance profiling (be aware of load/space)
;xdebug.mode=profile
;   trace profiling (record args)
;xdebug.mode=trace

; starting mode
;   always (not recommended)
;xdebug.start_with_request=yes
;   only when specific get parameters / cookies are set
;   (?XDEBUG_TRIGGER=1, ?XDEBUG_PROFILE=1, ?XDEBUG_TRACE=1, ?XDEBUG_SESSION=1)
;   this is best in conjunction with Chrome extension "Xdebug helper"
xdebug.start_with_request=trigger
;   folder for analyzing profile dumps
xdebug.output_dir="/tmp/xdebug"
;   not needed, since it is already in /etc/php/8.4/fpm/conf.d/20-xdebug.ini
;zend_extension=xdebug.so

After these adjustments we restart PHP-FPM to apply the changes:

sudo service php8.4-fpm restart

Configure VSCode

To use Xdebug in Visual Studio Code, two extensions and a configuration adjustment are required. We will install:

• PHP Debug: for basic debugging functionality.
• PHP Profiler: For analyzing cachegrind files.

Finally, we create the configuration file launch.json in the .vscode folder of the project to be analyzed:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "ignore": ["**/vendor/**/*.php"]
        }
    ]
}

Install Chrome Extension

The Xdebug helper extension has proven to be useful for flexible debugging in the browser. This allows you to activate or deactivate Xdebug only when needed. You can also easily change the debug mode (for example, to switch from debugging to profiling).:

Configure WordPress

When using Xdebug in a WordPress environment, it may be useful to disable debugging within cronjobs when a debugging session is active. This makes debugging requests easier. To do this, add the following line to the wp-config.php a:

// disable wp cron on xdebug sessions
if (function_exists('xdebug_is_debugger_active') && xdebug_is_debugger_active()) {
    define('DISABLE_WP_CRON', true);
}

With this configuration, we have a powerful setup that allows us to master complex debugging problems precisely. Whether it's finding stubborn bugs or fine-tuning performance problems - Xdebug not only makes work more efficient, but also brings a new quality to development through control and clarity over the code.