Step-Debug PHP Scripts in PhpStorm Using Zero‑Configuration Xdebug

Desired Outcome

\n

You want to step-debug a PHP script directly in PhpStorm, with the IDE pausing at breakpoints and showing live variable values without manually mapping ports for common setups.

\n

Necessary Prerequisites

\n

\n
1. PhpStorm installed (2023.3 or newer recommended for improved Xdebug auto-detection).
\n
2. Xdebug installed as a PHP extension on your local or Docker PHP runtime.
\n
3. The xdebug.mode setting in php.ini must include the debug token (e.g., xdebug.mode=debug).
\n
4. If debugging remotely in Docker, Docker Desktop must be running and the container network-accessible.
\n

\n

Focused Procedure

\n

\n
1. Verify Xdebug is active: open a PHP info page or run php -m | grep xdebug to confirm the extension loads.
\n
2. Set a breakpoint in the PhpStorm editor gutter next to the desired line.
\n
3. From the top-right toolbar, select or create a Run & Debug configuration. PhpStorm auto-detects Xdebug on port 9003 by default.
\n
4. Click the Debug button (bug icon). The status bar at the bottom turns green and shows Connected to Xdebug if the handshake succeeds.
\n
5. When the script reaches the breakpoint, execution pauses. The current line highlights in the editor. The Frames and Variables panels populate with the script's runtime state.
\n

\n

Expected Checks

\n

\n
• Status bar turns green with Connected to Xdebug.
\n
• The breakpoint is hit and the editor cursor jumps to the marked line.
\n
• Superglobals ($_GET, $_POST) and custom variables appear with expected values in the Variables panel.
\n
• Expression evaluation works: type any valid PHP expression in the Evaluate dialog to see runtime results.
\n

\n

Recovery Options

\n

\n
• If the status bar stays gray or shows Waiting for connection, verify that xdebug.mode includes debug and that no other process occupies port 9003.
\n
• For Docker setups, if breakpoints resolve incorrectly, open Settings → PHP → Servers, confirm the host and container document roots, then use the Path mapping tab to align local and container directories.
\n
• If Xdebug logs report failed to connect, check firewall rules or container port exposure (e.g., -p 9003:9003 in docker run).
\n
• As a last resort, explicitly set the Xdebug port in the Run/Debug Configuration → Xdebug, matching the port php.ini exposes.
\n