XDebug Debugging

Every DAMP project comes with XDebug pre-configured and ready to use. Set breakpoints, inspect variables, and step through your code like a pro - all from VS Code.

Quick Start

Debug your PHP code in three simple steps:

Features

Pre-Configured Setup

XDebug Configuration

Every project includes .devcontainer/xdebug.ini:

[XDEBUG]
xdebug.mode = develop,debug,trace,coverage,profile
xdebug.start_with_request = trigger
xdebug.client_port = 9003

Why Trigger Mode?

Trigger mode means XDebug only activates when you explicitly request it, preventing unnecessary overhead. Use a browser extension or add ?XDEBUG_TRIGGER=1 to URLs to start debugging.

VS Code Launch Configuration

Included in .vscode/launch.json:

{
  "type": "php",
  "request": "launch",
  "name": "Listen for Xdebug",
  "port": 9003,
  "pathMappings": {
    "/workspace/yourproject": "${workspaceFolder}"
  }
}

Debugging Workflows

Basic Debugging

1. Set Breakpoint - Click next to line number
2. Press F5 - Start debug session
3. Navigate Code
   • Access your site in browser
   • XDebug triggers on breakpoint
   • Use debug toolbar to step through

Using Browser Extension

The easiest way to trigger XDebug is with a browser extension:

Chrome/Edge:

• Install Xdebug Helper
• Click the extension icon → Enable "Debug"
• Green bug icon means debugging is active
• Browse your site - breakpoints will trigger

Firefox:

• Install Xdebug Helper
• Same workflow as Chrome version

Without Extension: Add ?XDEBUG_TRIGGER=1 to any URL:

https://myapp.local/?XDEBUG_TRIGGER=1

Conditional Breakpoints

Set breakpoints that only trigger when conditions are met:

1. Right-click on breakpoint or gutter
2. Select "Add Conditional Breakpoint"
3. Enter condition (e.g., $count > 10)
4. Breakpoint only triggers when condition is true

Advanced Features

Inspecting Variables

View Current State:

• Hover over variables in code
• Expand in Variables panel
• See type, value, and structure

Modify During Debug:

• Right-click variable in panel
• Select "Set Value"
• Change value and continue execution

Watch Expressions

Monitor complex expressions:

// Watch these expressions:
$user->name
count($items)
$total > 100

Add in Watch panel to track changes throughout execution.

Exception Breakpoints

Break when exceptions are thrown:

1. Open Breakpoints panel
2. Click "+ Add Exception Breakpoint"
3. Choose exception types
4. Debugger stops on exceptions

Laravel Debugging

Artisan Commands

Debug Laravel artisan commands:

{
  "name": "Debug Artisan Command",
  "type": "php",
  "request": "launch",
  "program": "/workspace/yourproject/artisan",
  "args": ["your:command"],
  "cwd": "/workspace/yourproject"
}

Queue Workers

Debug queue jobs:

1. Set breakpoint in job handle() method
2. Start debug session (F5)
3. Dispatch job to queue
4. Debugger stops at breakpoint

Testing

Debug PHPUnit tests:

1. Set breakpoint in test method
2. Run test with coverage
3. Debugger stops at breakpoint in test

Common Use Cases

🐛 Hunting Bugs

Find that elusive bug causing issues:

// Set breakpoint here
public function calculateTotal($items) {
    $total = 0;
    foreach ($items as $item) {
        $total += $item->price; // Inspect $item here
    }
    return $total;
}

📊 Understanding Flow

Trace execution through complex code:

// Set breakpoints at each step
public function processOrder($order) {
    $this->validate($order);     // Step 1
    $this->charge($order);        // Step 2
    $this->fulfill($order);       // Step 3
    $this->notify($order);        // Step 4
}

🔍 Inspecting Data

See exact values during runtime:

// What does $data actually contain?
public function transform($data) {
    // Set breakpoint - inspect $data structure
    return $this->mapper->map($data);
}

Customization

Modify XDebug Settings

Edit .devcontainer/xdebug.ini for custom configuration:

[XDEBUG]
xdebug.mode = develop,debug,trace,coverage,profile
xdebug.start_with_request = trigger
xdebug.client_port = 9003

; Add custom settings:
xdebug.log = /tmp/xdebug.log
xdebug.max_nesting_level = 512

Rebuild Container: After changes, rebuild with Ctrl+Shift+P → "Dev Containers: Rebuild Container"

Troubleshooting