Skip to content

Understanding Xdebug

Jump to bottom
Anuragh K P edited this page Mar 23, 2026 · 1 revision

Understanding Xdebug

What is Xdebug?

Xdebug is a PHP extension that provides advanced debugging capabilities including:

  • Interactive Debugging - Control script execution with breakpoints
  • Variable Inspection - Examine variables, arrays, and objects
  • Stack Traces - View the call stack at any point
  • Profiling - Analyze script performance
  • Code Coverage - Track which code was executed
  • Remote Debugging - Debug scripts running on remote servers

How Xdebug Works

Architecture Overview

┌─────────────────┐
│  PHP Script     │
│  (with Xdebug)  │
└────────┬────────┘
         │
         │ DBGp Protocol
         │ (TCP or Unix Socket)
         ▼
┌─────────────────────────────┐
│  Xdebug MCP Server          │
│  (xdebug-mcp)               │
└────────┬────────────────────┘
         │
         │ MCP Protocol
         ▼
┌─────────────────────────────┐
│  Claude / IDE / Client      │
│  (Debugging Interface)      │
└─────────────────────────────┘

Execution Flow

  1. PHP Script Starts: Your PHP script runs with Xdebug extension loaded
  2. Xdebug Initializes: Xdebug listens for connections on configured port/socket
  3. Connection Made: Xdebug MCP Server connects to the debugging Xdebug process
  4. Session Created: A debug session is established for your script
  5. Breakpoints Applied: Any set breakpoints are configured
  6. Execution Control: You can step, run, and inspect variables
  7. Session Ends: When script completes, the session terminates

Xdebug Installation

On Linux/macOS

pecl install xdebug

Via Package Manager

Ubuntu/Debian:

sudo apt-get install php-xdebug

macOS (Homebrew):

brew install php-xdebug

Verify Installation

php -v | grep Xdebug

You should see: with Xdebug X.X.X

Xdebug Configuration

Basic Configuration (php.ini)

; Enable Xdebug
zend_extension=xdebug

; Mode: debug, profile, trace, coverage, gcstats
xdebug.mode = debug

; Client Host/Port
xdebug.client_host = localhost
xdebug.client_port = 9003

; Trigger (optional - only debug when requested)
xdebug.trigger_value = "debug"

; Log file (for troubleshooting)
xdebug.log = /tmp/xdebug.log
xdebug.log_level = 10

Unix Socket Configuration

zend_extension=xdebug
xdebug.mode = debug

; Use Unix socket instead of TCP
xdebug.client_host = /tmp/xdebug.sock
xdebug.client_port = 0

Xdebug Modes Explained

Debug Mode

Enables interactive debugging - the main mode for step-by-step execution.

xdebug.mode = debug

Profile Mode

Generates profiling data for performance analysis.

xdebug.mode = profile

Trace Mode

Logs all function calls and execution flow.

xdebug.mode = trace

Coverage Mode

Tracks which lines of code are executed.

xdebug.mode = coverage

Multiple Modes

You can enable multiple modes:

xdebug.mode = debug,profile

Key Concepts

Breakpoints

A point in code where execution pauses, allowing inspection.

  • Line Breakpoints - Pause at specific line numbers
  • Conditional Breakpoints - Pause when condition is true
  • Watch Expressions - Pause when variable value changes

Stack Frames

The call stack showing which functions are executing and in what order.

Frame 0: current_function()     (line 25, file.php)
Frame 1: parent_function()      (line 50, file.php)
Frame 2: {main}                 (line 1, index.php)

Variables Inspection

Examine the state of:

  • Local variables
  • Global variables
  • Superglobals ($_GET, $_POST, etc.)
  • Object properties and methods
  • Array contents

Stepping

Control code execution:

  • Step In - Enter function calls
  • Step Over - Execute function but don't enter it
  • Step Out - Exit current function
  • Run - Continue until next breakpoint

Xdebug IDE Key

The IDE key is used by Xdebug to identify itself. Common values:

  • vscode - VS Code
  • phpstorm - PhpStorm
  • netbeans - NetBeans
  • xdebug-mcp - This MCP Server

Configure in php.ini:

xdebug.idekey = xdebug-mcp

Network Communication

TCP Connection (Default)

Client (Port 9003)
    ↓
PHP Script with Xdebug (DBGp)
    ↓
Xdebug MCP Server

Unix Socket Connection (Recommended for Local)

Client
    ↓
PHP Script with Xdebug (DBGp)
    ↓
/tmp/xdebug.sock (Unix Socket)
    ↓
Xdebug MCP Server

Benefits of Unix sockets:

  • Lower latency
  • Better security (file permissions)
  • No port conflicts
  • Suitable for local debugging

Performance Considerations

Xdebug has performance overhead when debugging:

  • Debug Mode: 5-10x slower
  • Trace Mode: 10-20x slower
  • Profile Mode: 2-5x slower

This is normal and expected. For production, disable Xdebug or use selective debugging.

Resources

Clone this wiki locally