Speed Up PHP Debugging with the Lightweight PHP Debugger Extension

PHP Debugger

A lightweight, high‑performance PHP debugging extension forked from Xdebug, removing all non‑debug features and optimized for near‑zero overhead when not active.

Note: This project is an experiment to show how quickly the PHP community can build tools using AI. The entire extension—branching, trimming, optimizing, renaming—was completed in days using PhpStorm, Claude Code, and OpenClaw, demonstrating rapid development and proving PHP tools can be industry‑leading.

Why Choose PHP Debugger?

Only +4% overhead when loaded but inactive (vs. Xdebug +324%).

Drop‑in replacement for Xdebug – no changes to existing configuration, IDE settings, or workflow.

Debug‑only – no profiler, code coverage, or tracing features.

Full DBGp protocol support – compatible with PhpStorm, VS Code, and any DBGp‑compatible IDE.

Performance Comparison

Running bench.php on Apple Silicon with PHP 8.5.3, extension loaded, xdebug.mode=debug, no IDE connection:

Configuration          Execution Time   Overhead
No debugger             0.139s            —
PHP Debugger           0.145s            +4%
Xdebug                 0.589s            +324%

Installation

Manual download

Download the binary for your platform from the Releases page, place it in your PHP extensions directory, and add to php.ini:

zend_extension=php_debugger.so

Planned one‑click installers (under construction)

One‑click script:

curl -fsSL https://raw.githubusercontent.com/pronskiy/php-debugger/main/install.php | php

Using PIE (PHP Installer for Extensions):

pie install pronskiy/php-debugger

Configuration

PHP Debugger supports both php_debugger.* and xdebug.* INI prefixes. Existing Xdebug settings work unchanged.

; Both syntaxes are valid:
php_debugger.mode = debug
php_debugger.client_host = 127.0.0.1
php_debugger.client_port = 9003
php_debugger.start_with_request = trigger

; Xdebug‑compatible syntax (also works):
xdebug.mode = debug
xdebug.client_host = 127.0.0.1
xdebug.client_port = 9003
xdebug.start_with_request = trigger

IDE Configuration

PhpStorm

After swapping the extension, the original debugging configuration works without changes. See the official PhpStorm Xdebug guide.

VS Code

Directly compatible; no configuration changes required.

Compatibility with Xdebug

PHP Debugger is a direct replacement for Xdebug’s debugging mode. Feature comparison:

Feature                         PHP Debugger    Xdebug
extension_loaded("xdebug")      true            true
extension_loaded("php_debugger") true            false
Supports xdebug.* INI           yes             yes
xdebug_break() function          yes             yes
XDEBUG_SESSION trigger           yes             yes
Step debugging (DBGp)            full support    support
Code coverage                    use pcov       support
Profiler                         removed        support
Tracing                           removed        support

Optional new naming (coexists with old)

You may use the new INI names, which are fully compatible with Xdebug’s old names:

INI : php_debugger.mode, php_debugger.client_host, etc.

Functions : php_debugger_break(), php_debugger_info(), php_debugger_connect_to_client(), php_debugger_is_debugger_active(), php_debugger_notify().

Triggers : PHP_DEBUGGER_SESSION, PHP_DEBUGGER_SESSION_START, PHP_DEBUGGER_TRIGGER.

System Requirements

PHP 8.2, 8.3, 8.4 or 8.5