Debugging PHP with Xdebug and VS Code

Xdebug connects a PHP request to a VS Code debugging listener, enabling breakpoints and step-through inspection.

What It Does

Trigger-based debugging avoids slowing every request. VS Code requires a PHP debug adapter extension and a matching Xdebug port.

Requirements and Compatibility

Use a supported PHP runtime and install any third-party tool or extension explicitly shown in the examples. Commands should be run from the project root unless stated otherwise.

Syntax, Inputs and Results

The examples separate configuration, the smallest working operation and a realistic follow-up task. Adapt file paths and dependency versions to your own project.

Example 1: Basic Use

Trigger-based debugging avoids slowing every request.

zend_extension=xdebug
xdebug.mode=debug,develop
xdebug.start_with_request=trigger
xdebug.client_port=9003
xdebug.discover_client_host=0

Example 2: Another Case

VS Code requires a PHP debug adapter extension and a matching Xdebug port.

{
  "version": "0.2.0",
  "configurations": [{
    "name": "Listen for Xdebug",
    "type": "php",
    "request": "launch",
    "port": 9003
  }]
}

Practical Example

Exception locations can point to the failing code; redact secrets.

<?php
function sendReport(): void { throw new RuntimeException('Delivery failed'); }
try { sendReport(); } catch (RuntimeException $e) {
    error_log($e->getMessage() . ' at ' . $e->getFile() . ':' . $e->getLine());
}

For production, apply the compatibility and edge-case limits described below.

Important Behavior and Edge Cases

Keep profiling and step debugging disabled on ordinary production traffic.

Comparison with Related Functions and Tools

Subject	Key difference
Step debugging vs profiling	Step debugging pauses individual statements; profiling records aggregate runtime cost.

Common Beginner Mistakes

Mistake	Correct approach
Enabling the debugger for every production request	Use controlled triggers and disable development modes in production.
Skipping the prerequisite of this specific workflow	Install or configure the named tool and confirm the example can actually run.
Ignoring edge conditions	Keep profiling and step debugging disabled on ordinary production traffic.

Key Takeaways

Xdebug connects a PHP request to a VS Code debugging listener, enabling breakpoints and step-through inspection.
Keep profiling and step debugging disabled on ordinary production traffic.
Keep application configuration, source code and validation tests under version control.

Use these examples as a starting point, then validate the result with the actual PHP build, dependencies and inputs used by your application.