Debugging Guide

Debugging Guide

Complete Debugging Workflow

This guide walks through setting up and using the Xdebug MCP Server to debug PHP applications.

Step 1: Prepare Your PHP Environment

Install Xdebug

# Linux/macOS
pecl install xdebug

# Or via package manager
sudo apt-get install php-xdebug

Configure php.ini

Add to your php.ini file:

[xdebug]
zend_extension=xdebug
xdebug.mode=debug
xdebug.client_host=localhost
xdebug.client_port=9003
xdebug.idekey=xdebug-mcp
xdebug.log=/tmp/xdebug.log
xdebug.log_level=10

Verify Configuration

php -i | grep -i xdebug

Output should show:

with Xdebug vX.X.X
xdebug.mode => debug
xdebug.client_port => 9003

Step 2: Start the Xdebug MCP Server

Via npm

npm install -g xdebug-mcp
xdebug-mcp

Output:

[INFO] Xdebug MCP Server listening on localhost:9003

Via Docker

docker run -p 9003:9003 xdebug-mcp

Verify Server is Running

# Check if port 9003 is listening
netstat -tlnp | grep 9003
# or
lsof -i :9003

Step 3: Create a Test PHP Script

Create test-debug.php:

<?php
// Example script to debug

function calculate_sum($a, $b) {
    $result = $a + $b;  // Line 5 - Set breakpoint here
    return $result;
}

function main() {
    $x = 10;
    $y = 20;
    $sum = calculate_sum($x, $y);  // Line 11
    echo "Sum: " . $sum . "\n";
}

main();

Step 4: Trigger Debugging

Method 1: Direct PHP CLI

php test-debug.php

When script runs:

1. Xdebug connects to MCP Server on port 9003
2. MCP Server receives init packet
3. Script pauses at first breakpoint (if set)
4. You can inspect variables, step through code

Method 2: Web Server

Start PHP development server:

php -S localhost:8000

Visit in browser:

http://localhost:8000/test-debug.php?XDEBUG_SESSION=xdebug-mcp

The XDEBUG_SESSION parameter triggers debugging.

Method 3: Conditional Debugging

Configure selective debugging in php.ini:

xdebug.trigger_value=debug
xdebug.trigger=GET

Then debug only when:

http://localhost:8000/test-debug.php?debug=1

Step 5: Set Breakpoints

Using MCP Tools (Claude/IDE)

With the MCP client connected to the MCP Server:

Set breakpoint at test-debug.php:5

The MCP Server will send DBGp command:

breakpoint_set -t line -f file:///path/test-debug.php -n 5

Conditional Breakpoints

Set breakpoint at test-debug.php:11 when $sum > 25

Step 6: Execute and Debug

Execution Commands

run          // Continue execution until next breakpoint
step_into    // Step into function calls
step_over    // Step over function calls
step_out     // Exit current function
stop         // End debugging session

Inspect Variables

When paused at breakpoint:

Local Variables:

Get local variables

Returns:

$x = 10 (integer)
$y = 20 (integer)
$a = 10 (integer)
$b = 20 (integer)
$result = 30 (integer)

Inspect Specific Variable:

Get $sum

Returns:

$sum = 30 (integer)

Inspect Array:

Get $_GET

Returns:

$_GET = array(2) {
  ["debug"] => string(1) "1",
  ["var"] => string(5) "hello"
}

View Call Stack

Get stack trace

Returns:

Frame 0: calculate_sum() [line 5 in test-debug.php]
Frame 1: main() [line 11 in test-debug.php]
Frame 2: {main} [line 1 in test-debug.php]

Common Debugging Scenarios

Scenario 1: Debugging a Function

function process_user($userId) {
    $user = get_user($userId);     // Set breakpoint here
    $data = transform($user);       // Step through this
    return $data;
}

1. Set breakpoint at get_user() call
2. Run script
3. When paused, inspect $userId value
4. Step into get_user() to debug it
5. Continue stepping through code

Scenario 2: Inspecting Array/Object

$user = [
    'id' => 123,
    'name' => 'John',
    'email' => 'john@example.com'
];

// Set breakpoint here
echo $user['name'];

When paused:

1. Get $user variable
2. Inspect nested properties
3. Check array keys and values
4. Continue execution

Scenario 3: Debugging Loop

for ($i = 0; $i < 10; $i++) {
    $result = expensive_operation($i);  // Set breakpoint
    process($result);
}

1. Set breakpoint inside loop
2. Run - stops at first iteration
3. Inspect $i and $result
4. Use "Continue" to loop to next iteration
5. Use "Step Over" to skip function calls

Scenario 4: Exception Debugging

try {
    $data = risky_operation();  // Set breakpoint before
    process_data($data);
} catch (Exception $e) {
    // Breakpoint here
    log_error($e->getMessage());
}

1. Set breakpoint before risky operation
2. Step through to see where exception occurs
3. Inspect exception object properties
4. Check caught exception details

Advanced Debugging Techniques

Watch Variables

Monitor when variables change:

Watch $totalPrice

When value changes, execution pauses automatically.

Code Coverage

Track which lines executed:

Enable code coverage
Run script
Get coverage report

Performance Profiling

Profile script execution:

1. Enable profiling mode in php.ini:

xdebug.mode=profile,debug

2. Run script with debugging
3. Analyze performance data:

Get profiling data

Remote Debugging

Debug script on remote server:

1. Configure PHP on remote server (same php.ini)
2. Set client_host to your machine IP:

xdebug.client_host=192.168.1.100

3. Start MCP Server on your machine port 9003
4. Run script on remote server
5. MCP Server receives connection from remote Xdebug

Debugging Workflow Diagram

┌─────────────────────────────────────────┐
│  1. Start Xdebug MCP Server (port 9003) │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│  2. Configure PHP with Xdebug           │
│     - xdebug.mode=debug                 │
│     - xdebug.client_port=9003           │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│  3. Create/Open PHP Script              │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│  4. Set Breakpoints in Code             │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│  5. Trigger Script Execution            │
│     - CLI: php script.php               │
│     - Web: Visit URL with debug param   │
└────────────────┬────────────────────────┘
                 │
         ┌───────┴───────┐
         │               │
    ┌────▼──────┐   ┌────▼──────┐
    │ Xdebug    │   │  Connect  │
    │ connects  │──▶│  to MCP   │
    │ to PHP    │   │  Server   │
    └───────────┘   └────┬──────┘
                         │
         ┌───────────────┴───────────────┐
         │                               │
    ┌────▼──────┐              ┌────────▼──┐
    │ Paused at │              │ Inspect   │
    │ Breakpoint│              │ Variables │
    └────┬──────┘              └───────────┘
         │
    ┌────▼──────────────────────────────┐
    │ Step/Run/Continue to next         │
    │ breakpoint                        │
    └────┬──────────────────────────────┘
         │
    ┌────▼──────────────────────────────┐
    │ Analysis Complete                 │
    │ Send stop command                 │
    └───────────────────────────────────┘

Troubleshooting Debugging

"Connection refused" error

Problem: MCP Server not running or wrong port Solution:

# Check if server running
lsof -i :9003

# Restart server
xdebug-mcp

Script executes without pausing

Problem: Breakpoints not set or no breakpoints exist Solution:

1. Verify breakpoint set: Get breakpoints
2. Check file path matches: file:// + absolute path
3. Ensure line number is valid (not blank/comment)

Xdebug not connecting

Problem: PHP not connecting to MCP Server Solution:

1. Check php.ini: php -i | grep xdebug
2. Verify xdebug.mode = debug
3. Check client_host and client_port match
4. View Xdebug log: tail -f /tmp/xdebug.log

Slow debugging

Problem: Debugging is very slow Solution:

1. Normal - Xdebug adds 5-10x overhead
2. Reduce breakpoints
3. Use step_over instead of step_into
4. Disable unnecessary features

Resources

• Xdebug Debugging Documentation
• DBGp Protocol Reference
• PHP Development Server Docs