VS Code debugging requires a working Xdebug extension in the PHP runtime and a matching debug listener in the editor.
This guide focuses on a plain PHP workflow and can be adapted to framework-based projects where the same tools apply.
Check the PHP runtime
Run php -v and php --ri xdebug using the same PHP executable that runs the application. Install an Xdebug build compatible with that PHP version and operating system. Web-server PHP and CLI PHP can load different php.ini files, so verify both when debugging browser requests.
Configure Xdebug 3
A typical development configuration is: zend_extension=xdebug, xdebug.mode=debug, xdebug.start_with_request=yes, xdebug.client_host=127.0.0.1, and xdebug.client_port=9003. The correct client host depends on where PHP runs. For containers or remote servers, it is often not localhost. Never expose a public debugging endpoint.
Create a VS Code launch configuration
Install the PHP Debug extension and create a .vscode/launch.json configuration with a listener on port 9003. A minimal configuration uses the php debug type, a descriptive name, and port: 9003. Add path mappings when PHP executes files in a container or remote host whose paths differ from the local workspace.
Set and test breakpoints
Start the debugger listener, place a breakpoint on an executable line, and trigger the matching PHP request. Inspect the call stack, local variables, and evaluated expressions. If the breakpoint is not reached, verify the Xdebug log, port, client host, path mapping, and active php.ini.
Keep debugging isolated
Enable Xdebug only in development or controlled staging environments. Disable it for public production traffic unless a carefully secured operational procedure explicitly requires it. Debugging can affect performance and may expose sensitive runtime details.
Practical verification checklist
- Confirm the editor uses the intended PHP 8.4 executable.
- Open the repository root and verify Composer dependencies.
- Run PHP linting and the project’s automated tests.
- Check that editor diagnostics match command-line results.
- Keep local credentials and production data out of the workspace.
Conclusion
Troubleshoot the connection from the PHP process to the editor in order: loaded extension, Xdebug mode, client host and port, listener, and path mapping. This is more reliable than repeatedly changing editor settings at random.