Xdebug extends PHP with debugging and diagnostic capabilities. Step debugging lets a developer pause execution, inspect variables and follow control flow rather than relying only on temporary var_dump() calls.
Match the extension build
Use the official Xdebug installation wizard or compatibility instructions to identify the correct binary for the PHP version, operating system, architecture and thread-safety mode. A mismatched DLL or shared object will not load. Confirm that the extension appears in php -v or php -m for the runtime being debugged.
Configure the correct php.ini
Find the active configuration with php --ini for CLI PHP and inspect the web server's PHP configuration separately. A typical local setup enables the extension and sets xdebug.mode=debug and xdebug.start_with_request=trigger. Use the IDE's documented client port and avoid exposing the debug listener to untrusted networks.
Connect the IDE
Start the IDE's debug listener, set a breakpoint and trigger a request using the configured mechanism. If PHP runs in a container, configure host reachability and path mappings so file paths inside the container correspond to local project files.
Diagnose connection problems
Check that the extension loaded, the correct php.ini was edited, the IDE is listening, firewall rules permit the local connection and the client host is reachable. Do not enable verbose debugging on a public production site.
Use debugging responsibly
Inspect secrets and personal data carefully; variable panels can expose credentials and session contents. Remove temporary diagnostics and disable debugging when the task is complete.
Further reading
- Xdebug documentation: https://xdebug.org/docs/step_debug
- Xdebug installation: https://xdebug.org/docs/install