Configure Xdebug Step Debugging in PhpStorm for PHP Web and CLI Scripts

Desired outcome

Attach PhpStorm to a running PHP process and step through breakpoints while inspecting local variables, superglobals, and the call stack during a web request or CLI script.

Prerequisites

• PhpStorm project with a configured PHP interpreter.
• Xdebug extension installed and enabled.
• php.ini configured for debugging (see example below).
• IDE debug port not blocked by firewall.

Example php.ini settings (Xdebug 3)

xdebug.mode=debug
xdebug.client_host=127.0.0.1
xdebug.client_port=9003

Example php.ini settings (Xdebug 2)

xdebug.remote_enable=1
xdebug.remote_host=127.0.0.1
xdebug.remote_port=9000

Procedure

1. Prepare the IDE listener

1. In PhpStorm choose Run | Edit Configurations.
2. Click the + button, select PHP Web Page for web scripts or PHP Script for CLI scripts.
3. If the server runs remotely, set Path mappings so that the project directory maps to the remote source path.
4. Close the dialog.
5. Click the telephone icon in the top‑right toolbar to start listening for PHP debug connections.

2. Trigger the debugging session

For a web request: open the URL that maps to the script with breakpoints in a browser (or use curl). For a CLI script: run the script from the command line or from the PhpStorm run configuration.

3. Set breakpoints

Click in the gutter next to the lines where you want execution to pause. Breakpoints appear as red dots.

Expected checks

• The Debug tool window appears and shows a suspended thread at the first breakpoint.
• Variables, watches, and the call stack are populated.
• Stepping commands (F7, F8, F9) advance execution as expected.
• When the request ends, the session detaches and the Debug tool window returns to idle.

Recovery options

• If no connection arrives:
  1. Verify the php.ini values (php -i | grep xdebug or php --ri xdebug).
  2. Restart PHP‑FPM or the web server to reload the configuration.
  3. Check that port 9003 (Xdebug 3) or 9000 (Xdebug 2) is free (netstat -tlnp | grep 9003).
  4. Toggle the IDE listener off and on (telephone icon).
  5. Review path mappings for directory mismatches.
• If a second process is already bound to the debug port, PhpStorm will silently fail to receive connections; stop the conflicting process or change the port in php.ini and the IDE listener settings.

Limitations and verification

• Xdebug 2 and Xdebug 3 use different configuration directives; ensure you edit the correct block for your version.
• Breakpoints in symlinked or vendor files may not hit if path mappings do not resolve the real file path.
• Do not expose xdebug.client_host to untrusted networks; debugging can leak source code and data.
• Practical verification:
  1. Run php -m | grep -i xdebug to confirm the extension is loaded.
  2. Run php --ri xdebug and check that xdebug.mode equals debug (Xdebug 3) or that remote debugging is enabled (Xdebug 2).
  3. Before starting the IDE listener, use telnet 127.0.0.1 9003 (or 9000) to see if the port is accepting connections; a blank screen or Connected indicates the port is open.
  4. During a debugging session, open the Debug tool window and confirm that variables such as $_GET, $_POST, and custom locals are visible.