How to Install Xdebug for PHP on RHEL 7

Xdebug is the de facto debugging and profiling extension for PHP. It transforms PHP development from a cycle of var_dump() statements into a proper interactive debugging experience: you can set breakpoints, step through code line by line, inspect variable values at runtime, and generate detailed execution profiles to identify performance bottlenecks. On RHEL 7, installing Xdebug requires the Remi repository because the base system PHP packages do not include it. This guide covers installation, configuration for both step debugging and profiling, integration with VS Code, and how to start and manage debug sessions safely on a production-adjacent server.

Prerequisites

RHEL 7 server with root or sudo access
PHP installed (7.x recommended; this guide uses PHP 7.4 from Remi)
The Remi repository enabled (instructions below if not already configured)
VS Code installed on your local workstation with the PHP Debug extension by Xdebug
SSH access to the server for remote debugging

Step 1: Enable the Remi Repository

Xdebug for PHP 7.x on RHEL 7 is not available in the standard Red Hat or EPEL repositories. The Remi repository provides current PHP packages including Xdebug builds matched to each PHP version.

# Install EPEL first (Remi depends on it)
sudo yum install -y epel-release

# Install the Remi release package for RHEL 7
sudo yum install -y https://rpms.remirepo.net/enterprise/remi-release-7.rpm

# Install yum-utils for the yum-config-manager command
sudo yum install -y yum-utils

Enable the Remi repository for the PHP version you are running. If you are using PHP 7.4:

sudo yum-config-manager --enable remi-php74

For PHP 8.0 or 8.1, substitute remi-php80 or remi-php81 accordingly. All later steps remain the same.

Step 2: Install php-xdebug

With the correct Remi repository enabled, install the Xdebug package. The package manager will automatically install the version that matches your active PHP build.

sudo yum install -y php-xdebug

Confirm the installation and check the Xdebug version:

php -m | grep -i xdebug
# Expected output: Xdebug

php --version
# Output includes Xdebug version in parentheses, e.g.:
# with Xdebug v3.1.5, Copyright (c) 2002-2022, by Derick Rethans

The yum package places a configuration file at /etc/php.d/15-xdebug.ini (or similar path depending on PHP version). This file is loaded automatically by PHP.

Step 3: Configure Xdebug for Step Debugging

Xdebug 3.x (which ships with current Remi packages) uses a single xdebug.mode directive to control which features are active. This is cleaner than the Xdebug 2.x approach of individual enable flags.

Edit the Xdebug configuration file:

sudo vi /etc/php.d/15-xdebug.ini

Replace or extend its contents with the following step-debugging configuration:

; Load the extension (this line may already be present)
zend_extension = xdebug.so

; -----------------------------------------------
; Xdebug 3 step-debugging configuration
; -----------------------------------------------

; Enable step debugging mode
xdebug.mode = debug

; Start a debug session automatically on every request (useful for CLI)
; For web requests, use XDEBUG_SESSION cookie or query param instead
xdebug.start_with_request = trigger

; IP address of the machine running the debugger (your workstation)
; Use 'localhost' if debugging locally, or your workstation's IP for remote
xdebug.client_host = 127.0.0.1

; Port the debugger listens on (9003 is the Xdebug 3 default)
xdebug.client_port = 9003

; Timeout in milliseconds waiting for IDE to connect
xdebug.connect_timeout_ms = 2000

; Maximum nesting level to prevent infinite recursion crashes
xdebug.max_nesting_level = 256

; Log file for Xdebug connection diagnostics (disable in production)
; xdebug.log = /tmp/xdebug.log

After saving, restart your web server or PHP-FPM:

sudo systemctl restart php-fpm
# or for mod_php with Apache:
sudo systemctl restart httpd

Step 4: Configure VS Code for PHP Debugging

On your local workstation, open VS Code and install the PHP Debug extension (publisher: xdebug.php-debug). Then create a launch configuration for your project.

Open the Run and Debug panel (Ctrl+Shift+D), click create a launch.json file, and select PHP. VS Code generates a default configuration. Edit it to match your setup:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/var/www/html": "${workspaceFolder}"
            }
        },
        {
            "name": "Launch current script in CLI",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9003,
            "runtimeExecutable": "php"
        }
    ]
}

The pathMappings object is critical for remote debugging: it maps the server-side file path (left) to your local workspace path (right). Without this, VS Code cannot map breakpoints to server-side execution.

Step 5: Set Up an SSH Tunnel for Remote Debugging

Xdebug connects from the server back to your IDE. If your workstation is not directly reachable from the server (e.g., you are behind NAT), use an SSH reverse tunnel. Run this on your workstation:

# Replace user@rhel7server with your actual SSH target
ssh -R 9003:localhost:9003 user@rhel7server

This forwards port 9003 on the server to port 9003 on your workstation. While the tunnel is open and VS Code is listening, Xdebug connections from the server will arrive at your IDE.

Alternatively, update xdebug.client_host to your workstation’s public or LAN IP and ensure port 9003 is reachable (add a firewall rule if needed):

sudo firewall-cmd --add-port=9003/tcp --zone=trusted --permanent
sudo firewall-cmd --reload

Step 6: Start and Use a Debug Session

Start the VS Code listener by pressing F5 with the “Listen for Xdebug” configuration selected. The status bar turns orange and shows “Listening on port 9003”.

Trigger a debug session from the browser by appending ?XDEBUG_SESSION=1 to any URL of your application:

http://rhel7server/index.php?XDEBUG_SESSION=1

Alternatively, install the Xdebug Helper browser extension (available for Chrome and Firefox), which sets the XDEBUG_SESSION cookie with a single click.

For CLI scripts, set the trigger via environment variable:

XDEBUG_SESSION=1 php /var/www/html/artisan migrate

VS Code will pause execution at the first breakpoint. You can then step through code with F10 (step over), F11 (step into), and F5 (continue). The Variables panel shows all local and global variables in scope.

Step 7: Enable Profiling Mode

Xdebug’s profiler generates cachegrind-format output files that can be analysed with tools like KCacheGrind or QCacheGrind to visualise which functions consume the most time and are called most frequently.

To enable profiling, change xdebug.mode in your ini file:

; Enable profiling (you can also combine: xdebug.mode = debug,profile)
xdebug.mode = profile

; Write profiler output files to this directory
xdebug.output_dir = /tmp/xdebug_profiles

; Trigger profiling per-request with ?XDEBUG_PROFILE=1
xdebug.start_with_request = trigger

; Naming pattern for output files
xdebug.profiler_output_name = cachegrind.out.%p.%t

sudo mkdir -p /tmp/xdebug_profiles
sudo chown apache:apache /tmp/xdebug_profiles
sudo systemctl restart php-fpm

Trigger profiling for a single request:

curl "http://localhost/index.php?XDEBUG_PROFILE=1"
ls /tmp/xdebug_profiles/
# cachegrind.out.12345.1685000000

Copy the cachegrind file to your workstation and open it with KCacheGrind or the PHP Profiler VS Code extension to visualise call trees.

Step 8: Disable Xdebug in Production

Xdebug adds measurable overhead and should never run on a public-facing production server. The safest approach is to keep the configuration file present but disabled, switching it on only when an active debugging session is needed.

# Disable by renaming the ini file
sudo mv /etc/php.d/15-xdebug.ini /etc/php.d/15-xdebug.ini.disabled
sudo systemctl restart php-fpm

# Re-enable when needed
sudo mv /etc/php.d/15-xdebug.ini.disabled /etc/php.d/15-xdebug.ini
sudo systemctl restart php-fpm

Alternatively, set xdebug.mode = off in the ini file. This loads the extension but disables all functionality with near-zero performance impact, making it easy to enable a specific mode without a service restart in some configurations.

Xdebug transforms PHP development on RHEL 7 from guesswork into a precise, interactive process. By installing from the Remi repository, configuring the correct Xdebug 3 directives, and pairing the extension with VS Code’s PHP Debug plugin, you gain full step-debugging capability for both web and CLI scripts. The profiling mode adds another dimension: rather than guessing where slowdowns occur, you get hard data on function call counts and cumulative execution time, enabling targeted optimisation. Always remember to disable or remove Xdebug from publicly-accessible production environments to protect both security and performance.

How to Install Xdebug for PHP on RHEL 7