Skip to content

Xdebug

Jump to bottom
Technomantus Corvi edited this page Sep 5, 2026 · 1 revision

Local Development with Xdebug

1. Install

sudo apt install php-xdebug
sudo phpenmod xdebug
php -v   # should show: with Xdebug v3.x.x, ...

2. Configure xdebug.ini 

php --ini   # find the config file location

Add (typically /etc/php/8.1/mods-available/xdebug.ini):

zend_extension=xdebug.so
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003

xdebug.mode=debug is required for step debugging (develop alone does NOT work). Verify:

php -i | grep -i "xdebug.mode\|xdebug.start_with_request"

3. Editor extension

Install PHP Debug (xdebug.php-debug) in Antigravity/VS Code.

4. launch.json 

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

Don't add pathMappings for purely local dev (editor and server on the same machine) — a wrong or placeholder value leaves breakpoints unresolved and they never trigger. (Docker is different — see Docker.)

5. Debug

  1. Select "Listen for Xdebug", press F5.
  2. php -S localhost:8050 -t public public/index.php (from the project root).
  3. Set breakpoints, visit http://localhost:8050.

Troubleshooting

  • Confirm something listens on the port: sudo ss -ltnp | grep 9003
  • Enable Xdebug's own log to diagnose:
  xdebug.log=/tmp/xdebug.log
  xdebug.log_level=7

Check cat /tmp/xdebug.log after a request — look for whether breakpoint_set shows resolved or unresolved. unresolved usually means a pathMappings mismatch or that the breakpoint file path doesn't match what's actually being executed.

Clone this wiki locally