PHP Development

Debug PHP Applications in VS Code with Xdebug

Configure Xdebug 3 and the VS Code PHP Debug extension to step through PHP requests, inspect variables, and diagnose application behavior.

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.

Official documentation

Share this page Help other developers discover this resource.