Xdebug Debugging Setup

DAMP comes with Xdebug pre-configured and ready to use with VS Code. No complex configuration or setup required - just set breakpoints and start debugging your PHP applications immediately.

What is Xdebug?

Xdebug is a powerful debugging and profiling tool for PHP that provides:

Debugging Features

• Step-through debugging - Execute code line by line
• Breakpoints - Pause execution at specific points
• Variable inspection - Examine variable values and types
• Call stack - View function call hierarchy
• Watch expressions - Monitor specific variables or expressions

Additional Features

• Error reporting - Enhanced error messages and stack traces
• Code coverage - Track which code is executed during tests
• Profiling - Performance analysis and bottleneck identification
• Remote debugging - Debug code running in containers or remote servers

Zero Configuration

DAMP configures Xdebug automatically:

• Pre-installed in all PHP containers
• VS Code integration ready immediately
• Port forwarding configured automatically
• Path mapping set up correctly

Full Feature Set

All Xdebug features available:

• Step debugging with breakpoints
• Variable inspection and modification
• Call stack navigation
• Exception breakpoints

Performance Optimized

Xdebug configured for development:

• On-demand activation - no performance impact when not debugging
• Smart triggering - only activates when needed
• Efficient communication with VS Code

Quick Start Debugging

Basic Debugging Workflow

1. Open Project in VS Code

   Click “Open in VS Code” from your DAMP project card, or open the project folder in VS Code and reopen in DevContainer.

2. Set a Breakpoint

   Click in the gutter next to any line of PHP code to set a breakpoint.

3. Start Debug Listener

   Press F5 or click Run → “Start Debugging” in VS Code.

   You’ll see “Listening for Xdebug” in the debug console.

4. Trigger Code Execution

   Make a request to your application:

   • Visit your project URL in browser
   • Make an API request
   • Run a command line script

   💡 Tip: To trigger Xdebug debugging from your browser, use the Xdebug Helper Chrome extension. Enable it for your project domain to automatically set the required cookie and activate debugging for your requests.

5. Debug Interactively

   When your breakpoint is hit:

   • Code execution pauses
   • Variables panel shows current values
   • Call stack displays execution path
   • Debug console allows expression evaluation

Debug Configuration

Automatic Configuration

DAMP automatically creates the necessary debug configuration files:

VS Code Launch Configuration

// .vscode/launch.json (auto-generated)
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch application",
            "type": "php",
            "request": "launch",
            "program": "${workspaceFolder}/index.php",
            "cwd": "${workspaceFolder}",
            "port": 9003
        },
        {
            "name": "Listen for XDebug",
            "type": "php",
            "request": "launch",
            "port": 9003
        },
        {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9003
        }
    ]
}

Xdebug PHP Configuration

; xdebug.ini (automatically configured in container)
[xdebug]
xdebug.mode = develop,debug,trace,coverage,profile
xdebug.start_with_request = trigger
xdebug.client_port = 9003

Custom Configuration

You can customize debug behavior if needed you can find xdebug.ini file inside .devcontainer folder

Debug Modes

; Different Xdebug modes
xdebug.mode=debug               # Step debugging only
xdebug.mode=debug,develop       # Debugging + enhanced var_dump
xdebug.mode=debug,coverage      # Debugging + code coverage
xdebug.mode=debug,profile       # Debugging + performance profiling

Trigger Methods

; Control when Xdebug activates
xdebug.start_with_request=yes      # Always debug
xdebug.start_with_request=trigger  # Only when triggered
xdebug.start_with_request=no       # Manual activation only

Tip

When using xdebug.start_with_request=trigger, you can easily activate debugging sessions from your browser using the Chrome extension Xdebug helper. This extension adds a button to your browser toolbar that lets you enable or disable Xdebug triggers for your requests, making it simple to start debugging only when needed.

Debugging Techniques

Basic Debugging Controls

Debug Toolbar

When debugging is active, use these controls:

• Continue (F5) - Resume execution until next breakpoint
• Step Over (F10) - Execute current line, don’t enter functions
• Step Into (F11) - Enter function calls to debug inside them
• Step Out (Shift+F11) - Complete current function and return
• Restart (Ctrl+Shift+F5) - Restart debug session
• Stop (Shift+F5) - Stop debugging

Breakpoint Types

Line Breakpoints

• Click gutter to set/remove
• Right-click for conditional breakpoints
• Enable/disable without removing

Conditional Breakpoints

• Right-click breakpoint → “Edit Breakpoint”
• Set condition: $user === 'Alice'
• Only breaks when condition is true

Exception Breakpoints

• Break when exceptions are thrown
• Configure in VS Code debug panel
• Useful for catching errors early

Advanced Debugging

Variable Inspection

Variables Panel

• View all variables in current scope
• Expand arrays and objects
• See variable types and values
• Watch values change as you step

Watch Expressions

• Add expressions to monitor continuously
• Examples: $user, count($users), $this->property
• Updates automatically as you debug

Debug Console

• Evaluate expressions interactively
• Execute PHP code in current context
• Test variable values and function calls

Call Stack Navigation

• View execution path - see how you got to current point
• Click stack frames - jump to different points in execution
• Inspect variables at each stack level
• Understand program flow better

Debugging Different Scenarios

Web Request Debugging

For debugging web pages and API endpoints:

1. Set breakpoints in controllers, models, or middleware
2. Start debug listener in VS Code (F5)
3. Make web request through browser or API client
4. Debug when breakpoint hits

Command Line Debugging

For debugging Artisan commands or scripts:

1. Set breakpoints in command code
2. Use “Debug current script” configuration
3. Run command in VS Code terminal:

   php artisan your:command

4. Debug interactively

Profiling and Performance

Performance Profiling

Enable Xdebug profiling for performance analysis:

; Enable profiling
xdebug.mode=debug,profile
xdebug.output_dir=/tmp/xdebug
xdebug.profiler_output_name=cachegrind.out.%p

Code Coverage

Track code coverage during testing:

; Enable coverage
xdebug.mode=debug,coverage

Use with PHPUnit:

./vendor/bin/phpunit --coverage-html coverage/

Troubleshooting Xdebug

Common Issues

Breakpoints Not Working

Symptoms: Breakpoints are set but not being hit

Solutions:

1. Check debug listener - Ensure VS Code shows “Listening for Xdebug”
2. Verify Xdebug is loaded:

   php -m | grep xdebug

3. Check path mappings in launch.json
4. Restart debug session and try again

Cannot Connect to Xdebug

Symptoms: VS Code can’t connect to Xdebug

Solutions:

• Check port forwarding in DevContainer
• Verify Xdebug configuration:

  php -i | grep xdebug

• Check firewall settings on host machine
• Restart DAMP project containers

Slow Debugging Performance

Symptoms: Debugging is very slow

Solutions:

• Use trigger mode: xdebug.start_with_request=trigger
• Disable when not needed: Set xdebug.mode=off
• Limit debugging scope: Use conditional breakpoints
• Close unused debug sessions

Path Mapping Issues

Symptoms: Breakpoints in wrong files or not found

Solutions:

{
    "pathMappings": {
        "/var/www/html": "${workspaceFolder}",
        "/var/www/html/vendor": "${workspaceFolder}/vendor"
    }
}

Debug Information Commands

Get Xdebug information:

# Check if Xdebug is loaded
php -m | grep xdebug

# Show Xdebug configuration
php -i | grep xdebug

# Show loaded extensions
php --re xdebug

# Test Xdebug connectivity
php -dxdebug.start_with_request=yes -r "var_dump('debugging works');"

Log Analysis

Check Xdebug logs for connection issues:

# View Xdebug log
tail -f /tmp/xdebug.log

# Common log entries
[Xdebug] Could not connect to debugging client
[Xdebug] Connected to debugging client
[Xdebug] Disconnected from debugging client

Xdebug Pro Tips

• Use keyboard shortcuts for faster debugging (F5, F10, F11)
• Right-click variables for quick actions (copy value, add to watch)
• Use debug console for quick expression evaluation
• Set conditional breakpoints to debug specific scenarios
• Learn call stack navigation to understand complex execution flows

With DAMP’s pre-configured Xdebug setup, you can focus on debugging your application logic rather than fighting with debugging tool configuration. Happy debugging!