Xdebug Setup

Install Xdebug

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

# Install via PECL
pecl install xdebug

# Enable in php.ini
zend_extension=xdebug

# Verify installation
php -v

PHP Configuration

; php.ini for development
[xdebug]
zend_extension=xdebug

; Enable remote debugging
xdebug.mode=debug,develop,coverage
xdebug.start_with_request=yes
xdebug.remote_host=127.0.0.1
xdebug.remote_port=9003
xdebug.remote_autostart=1

; IDE key
xdebug.idekey=PHPSTORM

; Profiling
xdebug.output_dir=/tmp/xdebug
xdebug.profiler_output_name=trace.%p-%t

Verify Configuration

# Check Xdebug mode
php -r "phpinfo();" | grep xdebug

# Test connection
dxdebug-directory-connection

Key Points

• Use Xdebug 3.x for PHP 8.x
• Configure IDE to listen for debug connections
• Remote host must match your machine IP
• Port 9003 is default for Xdebug 3

Setting Breakpoints

// In IDE (PHPStorm)
// Click on line number to set breakpoint
// Or use keyboard shortcut (F9)

// Conditional breakpoint
// Right-click breakpoint > Edit > Add condition
$productSku = 'TEST-001';
// Condition: $sku === 'TEST-001'

// Log breakpoint (no pause)
// Right-click breakpoint > Edit > Check "Log to console"
$this->logger->debug('Reached this point');

Breakpoint Types

// Line breakpoint - pauses on specific line
public function process($data)
{
    $result = $this->validate($data); // Breakpoint here
    return $result;
}

// Method breakpoint - pauses when method is called
// IDE feature, set on method name
public function validate($data) // Breakpoint here
{
    // Validation logic
}

// Exception breakpoint - pauses on exception
// IDE: Run > Break at Exception > Uncaught Exceptions

// Watch expression
// IDE: Add watch for $data->getStatus()

Key Points

• Use conditional breakpoints for loops
• Log breakpoints for non-intrusive debugging
• Exception breakpoints catch errors early
• Remove breakpoints after debugging

Debugging Session

// Start debugging
// 1. Enable "Start Listening" in IDE
// 2. Set breakpoints
// 3. Trigger request (browser or CLI)
// 4. IDE will pause at breakpoint

// Step commands:
// F7: Step Into - enter function call
// F8: Step Over - execute function, don't enter
// Shift+F8: Step Out - exit current function
// F9: Resume - continue to next breakpoint

Debug Variables

// Inspect variables in debug panel
$product = $this->productFactory->create();
$product->setName('Test'); // Check $product in debugger

// Watch expressions
// Add: $product->getName()
// Add: count($products)

// Evaluate expression
// Alt+F8: type expression to evaluate
$product->getPrice() * 1.2

CLI Debugging

# Debug CLI commands
php -d xdebug.start_with_request=yes bin/magento cron:run

# Debug specific script
php -d xdebug.mode=debug script.php

Key Points

• Use Step Into for custom code, Step Over for vendor code
• Watch expressions track values across steps
• Evaluate expressions to test logic
• CLI debugging requires explicit Xdebug trigger

Enable Profiling

; php.ini
[xdebug]
xdebug.mode=profile
xdebug.output_dir=/tmp/xdebug
xdebug.profiler_output_name=profile.%p-%t

Profile Analysis

# Generate profile
# Access page, profile generated in /tmp/xdebug

# Convert to callgrind format
php ~/.phpspy/bin/pprof --convert callgrind /tmp/xdebug/profile.xdebug

# Analyze with KCachegrind
kcachegrind /tmp/xdebug/profile.xdebug

Flame Graphs

# Generate flame graph
php vendor/bin/perf --report flamegraph > /tmp/flamegraph.svg

# View in browser
open /tmp/flamegraph.svg

Code Coverage

# Generate code coverage with Xdebug
vendor/bin/phpunit --coverage-html /tmp/coverage app/code/Vendor/Module/Test/Unit/

# View coverage report
open /tmp/coverage/index.html

Key Points

• Profiling shows execution time per function
• Flame graphs visualize call stacks
• Code coverage shows tested code percentage
• Disable profiling in production (performance impact)