PHP Debugger is a step debugger for PHP, and nothing else. Every other feature that normally ships alongside one — the profiler, the coverage collector, the tracer — has been left out. What remains is a debugger you can leave switched on permanently, because when you are not using it you can barely tell it is there. It speaks the DBGp protocol, so PhpStorm, VS Code and anything else that already debugs PHP works with it, and it accepts Xdebug's INI settings, triggers and functions, so in most projects there is nothing to migrate beyond the line that loads the extension. And the debugger is no longer just for you: with DBGP Client, AI agents such as Claude Code can set breakpoints, step through your code and inspect its variables themselves.

📖 Full documentation: php-debugger.dev

• Near-zero overhead when loaded with no debug client connected
• Built for AI agents — with DBGP Client, your agent debugs PHP the way you would
• Drop-in compatible — existing INI settings, IDE configurations and helper functions keep working
• Always on — debugging starts with every request, so there is no trigger to remember
• Compiled in, or not — a PHP interpreter with the debugger built in, or a plain extension
• Debug-only — one job, done well, which is exactly why the rest of the time it costs so little

Measured in GitHub Actions with Valgrind instruction counts rather than wall-clock timing, averaged across every supported PHP version, with the extension loaded and no IDE connected — the state your machine is in almost all of the time.

The synthetic benchmark is the worst case: tight loops of function calls and little else, so the per-call cost has nowhere to hide. The closer you get to a real application, the smaller the share of the work the debugger touches.

Requirements: PHP 8.2, 8.3, 8.4, or 8.5.

Get the installer — macOS and Linux:

curl -fsSL https://github.com/php-debugger/installer/releases/latest/download/install.sh | sh

Windows:

powershell -c "irm https://github.com/php-debugger/installer/releases/latest/download/install.ps1 | iex"

Then install the debugger:

php-debugger install

That installs a self-contained PHP interpreter with the debugger compiled in and makes it the active php on your PATH. To keep the PHP you already have and install only the extension into it, use php-debugger install --extension-only. Either way, whatever it replaced is backed up and php-debugger uninstall puts it back.

See Installation for the full set of flags.

The images on Docker Hub are drop-in replacements for the official PHP images — change one line:

FROM phpdebugger/php:8.4-fpm

All official variants (cli, fpm, apache, zts, and their Alpine equivalents) for PHP 8.2–8.5, on amd64 and arm64. Everything from the official images works unchanged, including docker-php-ext-install. See Docker.

PIE, prebuilt binaries and building from source are covered in More install options.

There is almost certainly nothing to change. PHP Debugger speaks the protocol your editor already knows, on the port it already listens on — no plugin, no adapter, no new configuration. Start listening on port 9003, set a breakpoint, and run your code.

What changes is a habit rather than a setting: debugging is always available, so the switch is your editor's listener, not the debugger's configuration. There is no ?XDEBUG_SESSION_START=1 to remember and no browser extension to click.

See IDE Support, or the guides for PhpStorm and VS Code.

DBGP Client gives AI agents a real debugger. Its dbgp mcp command is an MCP server: the agent starts the PHP code itself, as a script or a web request, sets breakpoints, steps through it, and reads the call stack, variables, output and warnings — the same evidence you would look at in your IDE.

Install it — macOS and Linux:

curl -fsSL https://github.com/php-debugger/dbgp-client/releases/latest/download/install.sh | sh

Windows:

powershell -c "irm https://github.com/php-debugger/dbgp-client/releases/latest/download/install.ps1 | iex"

Then add it to your agent. For Claude Code:

claude mcp add dbgp -- dbgp mcp

Other agents take the same command, dbgp mcp, in their MCP settings. Then ask the agent to debug something:

Find out why the total on the checkout page is wrong: debug the request to /checkout with a breakpoint in CartService::total().

The two are made for each other. Because PHP Debugger is always on, the agent needs no trigger and no configuration change to start a session; and because dbgp only listens while the agent is debugging, the rest of the time PHP runs with the near-zero overhead shown above. It works with PHP in a container or on a server too, and -no-eval keeps the agent read-only. See the DBGP Client README for the options, and for a standalone command-line debugger for when you want to step through code in a terminal yourself.

Everything else — configuration, troubleshooting and the full reference — is at php-debugger.dev.

• Quick start
• User guide · Troubleshooting
• Settings · Functions · Environment variables

Released under The Xdebug License, version 1.03 (based on The PHP License).

This product includes Xdebug software, freely available from https://xdebug.org/.

PHP Debugger is built on the foundation of Xdebug, created and maintained by Derick Rethans since 2002. His two decades of work on PHP debugging tools made this project possible. Thank you, Derick.