Step Debugging Setup

## What step debugging is **Step debugging** means pausing a running PHP script at a breakpoint, inspecting variables, and executing it line by line from an IDE. **Xdebug** is the PHP extension that makes the engine stoppable, and it speaks **DBGp**, an open debugger protocol that most PHP IDEs and editors implement. Two roles are involved: - the **debugger engine**, Xdebug inside the PHP process; - the **debugging client**, the IDE or editor plugin that shows the code and sends "step over" or "evaluate" commands. ## Step 1: turn on debug mode Xdebug 3 enables features through a single setting, `xdebug.mode`. Its default is **`develop`**, which gives you the improved `var_dump()` and error output but **no step debugging**. ```ini ; 99-xdebug.ini (loaded when PHP starts) zend_extension=xdebug xdebug.mode=debug ; or develop,debug to keep the helpers ``` `xdebug.mode` can only be set in files read when the PHP process starts, such as `php.ini` or a `conf.d` file. It is **not** honoured in `.htaccess`, `.user.ini` or a PHP-FPM pool's `php_admin_value`. After changing it, restart PHP-FPM or the web server, because a running worker keeps the value it started with. ## Step 2: understand who connects to whom This is the part that surprises people used to attaching a debugger to a process: 1. The IDE opens a **listening socket**, which is its "start listening for debug connections" button. 2. A request starts in PHP, and Xdebug decides whether to debug it (Step 3). 3. If so, **Xdebug connects out** to `xdebug.client_host:xdebug.client_port`. 4. The IDE accepts, sets its breakpoints over DBGp, and the request runs until it hits one. | Setting | Default | Meaning | |---|---|---| | `xdebug.client_host` | `localhost` | where the IDE is listening | | `xdebug.client_port` | `9003` | the port the IDE listens on | | `xdebug.connect_timeout_ms` | `200` | how long Xdebug waits for the IDE to accept | Because the connection goes **from PHP to the IDE**, the machine running the IDE must accept an incoming connection on 9003. When PHP runs elsewhere, whether a VM, a remote server or a container, `client_host` must be an address **as seen from PHP** that reaches the IDE. ### Where client_host should point | PHP runs on | Typical `xdebug.client_host` | |---|---| | the same machine as the IDE | `localhost` (the default) | | a VM or remote server | the IDE machine's address as seen from that server | | a container on your laptop | a name that reaches the host, such as `host.docker.internal` | | a shared server used by several developers on one network | `xdebug.discover_client_host=1`, which connects back to the requesting address | The last option has no filter: anyone who can reach the web server can make it connect back to them, so it belongs on trusted networks only. ## Step 3: decide which requests are debugged `xdebug.start_with_request` decides when Xdebug tries to connect. Its default value, `default`, means **`trigger`** in debug mode: Xdebug only connects when the request carries a trigger, such as an `XDEBUG_TRIGGER` or `XDEBUG_SESSION` cookie, GET or POST variable, or environment variable, or when the code calls `xdebug_break()`. Setting it to `yes` makes every request try. ## Checking that it works - `xdebug_info()` shows an HTML diagnostics page, like `phpinfo()` for Xdebug, with the active modes, every setting, and any connection errors. - `xdebug_info('mode')` returns the enabled modes as an array, for example `['debug']`. - Setting `xdebug.log=/tmp/xdebug.log` records every connection attempt. ## Common first-time mistakes - Leaving `xdebug.mode` at `develop` and wondering why the IDE never reacts. - Editing the CLI `php.ini` while the web server's PHP-FPM reads a different one; check with `xdebug_info()` from a web request. - Expecting the IDE to connect to PHP, and opening port 9003 on the server instead of the IDE's machine. - Following an Xdebug 2 tutorial that uses `xdebug.remote_enable` and port 9000, which Xdebug 3 no longer uses.