Configure Xdebug in PhpStorm

Verify PHP before touching the IDE

Install Xdebug for the exact PHP binary and confirm it in php --version for CLI or xdebug_info() for web. Xdebug 3 commonly listens back to an IDE on port 9003 and requires debug mode. The active ini can differ between CLI and FPM.

Configure PhpStorm

Select the real local, Docker, WSL, or remote interpreter. Define a PHP server for web requests, including host and path mappings, then enable listening for PHP debug connections. Use a browser trigger or xdebug.start_with_request according to the development policy.

Diagnose path mapping

When a session arrives but misses a breakpoint, inspect the server filename. Map that exact container or remote prefix to the local source root. Avoid mapping vendor or public as the project root when composer.json lives above them.

Prove the smallest case

Break in a short script, inspect a variable, then move to PHPUnit and the framework front controller. Keep Xdebug off or trigger-only in shared environments and never expose its connection path indiscriminately.

Verification and maintenance

Configure Xdebug in PhpStorm was reviewed for this seed on 2026-08-09. Before adopting its recommendations, confirm current releases, platform support, licensing, extension publishers, and configuration syntax through JetBrains PhpStorm Xdebug Help at the official source linked below. Product status and plugin compatibility can change independently of this editorial record.

Test changes on a representative repository and keep Composer scripts, automated tests, static analysis, and version control authoritative. If official documentation no longer supports a claim made on /ide/phpstorm/xdebug/, mark the fact unknown or update it from a primary source rather than filling the gap from an old tutorial or download mirror.