Xdebug — Debugging & Profiling

Also Known As

TL;DR

Explanation

Xdebug is the standard PHP debugging and profiling tool. It integrates with IDEs (PhpStorm, VS Code) via DAP (Debug Adapter Protocol) for step-through debugging, variable inspection, and breakpoints. In profiling mode it generates cachegrind files readable by KCacheGrind or WebGrind. It powers PHPUnit's code coverage reports (requires xdebug.mode=coverage). Key modes: debug (step debugging), profile (performance analysis), trace (full execution trace), coverage. Never run Xdebug in production — it adds significant overhead and exposes a remote debugging port.

Watch Out

Common Misconception

Why It Matters

Common Mistakes

• Installing Xdebug in production — it adds significant overhead and exposes debug endpoints.
• Not configuring xdebug.mode = debug,coverage in php.ini — leaving it on develop mode without specific mode misses features.
• Not setting xdebug.start_with_request = trigger — without it, every request tries to connect to the debugger.
• Using var_dump as a substitute for a debugger — Xdebug step debugging shows the full call stack and variable state at any point.

Avoid When

• Never install Xdebug on a production server — it significantly degrades performance and exposes debugging interfaces.
• Disable xdebug.remote_enable and xdebug.mode=off in any non-development environment.

When To Use

• Use Xdebug in local development for step debugging, profiling, and code coverage.
• Use Xdebug's profiler output with KCacheGrind/QCacheGrind to identify performance bottlenecks.

Code Examples

; php.ini — Xdebug in production:
[xdebug]
zend_extension=xdebug.so
xdebug.mode=develop,debug
xdebug.start_with_request=yes ; Every request tries to debug — massive overhead
xdebug.client_host=localhost   ; Should never be active in production

; Xdebug 3 configuration
[xdebug]
zend_extension = xdebug
xdebug.mode    = debug,coverage
xdebug.start_with_request = trigger  ; activate only when triggered (not every request)
xdebug.client_host = host.docker.internal
xdebug.client_port = 9003

; VS Code step debugging:
; 1. Install PHP Debug extension
; 2. Set breakpoint
; 3. Start listening (F5)
; 4. Trigger request with XDEBUG_SESSION cookie or ?XDEBUG_SESSION=1

; Code coverage (PHPUnit):
$ phpunit --coverage-html=coverage/
; Requires xdebug.mode = coverage

References

• ↗ https://xdebug.org/docs/
• ↗ https://xdebug.org/docs/step_debug

Tags

Related Terms