Debug PHP with Xdebug 3

Last updated: August 25, 2026.

Xdebug connects PHP to an IDE so you can pause execution, inspect variables, and step through code. Xdebug 3 uses port 9003 and enables features through xdebug.mode.

Configure step debugging

[xdebug]
zend_extension=xdebug
xdebug.mode=debug,develop
xdebug.start_with_request=trigger
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.log=/tmp/xdebug.log

Restart PHP-FPM, Apache, or the relevant container after changing the configuration. Confirm the loaded configuration with:

php --ini
php -v
php -r "xdebug_info();"

Start a session

Set your IDE to listen for Xdebug connections. For a browser request, use an Xdebug helper extension or add an XDEBUG_TRIGGER value. For a command-line script:

XDEBUG_TRIGGER=1 php public/index.php

If the breakpoint is not reached

• Check that Xdebug is loaded by the same PHP runtime serving the request.
• Verify that the IDE is listening on port 9003.
• For containers or virtual machines, set xdebug.client_host to an address that reaches the host IDE.
• Read xdebug.log for connection attempts and failures.
• Map server paths to local project paths in the IDE.

See Xdebug’s step-debugging documentation for triggers and connection settings.