PHP Development

Configure Xdebug in PhpStorm

Connect PhpStorm to Xdebug 3, configure the PHP interpreter and debug port, map remote paths, and troubleshoot breakpoints.

The most important part of PhpStorm debugging is ensuring that the interpreter, Xdebug configuration, and server path mappings describe the same runtime.

This guide focuses on a plain PHP workflow and can be adapted to framework-based projects where the same tools apply.

Verify the configured interpreter

Open Settings | PHP and select the CLI interpreter used by the project. Confirm that PhpStorm detects Xdebug for that interpreter. If it does not, inspect the active php.ini and verify the extension is loaded by that exact PHP binary.

Configure Xdebug 3

A common development configuration uses xdebug.mode=debug, xdebug.start_with_request=yes, xdebug.client_port=9003, and a xdebug.client_host that resolves to the PhpStorm machine from the PHP process. Xdebug 3 uses port 9003 by default. Container and remote environments often require a host gateway or reachable workstation address.

Set the IDE debug port

In PhpStorm’s PHP | Debug settings, configure the Xdebug port to match xdebug.client_port. Start listening for incoming debug connections before triggering the request. Use the Xdebug helper or an explicit trigger mechanism when the project uses on-demand debugging.

Configure server mappings

For remote PHP, configure a server entry and map the remote document root to the local project directory. Incorrect mappings can cause PhpStorm to receive a debug connection but fail to associate the executing file with the local source file.

Secure and troubleshoot the setup

Check firewall rules, routing, Xdebug logs, PHP-FPM versus CLI configuration, and the actual port in use. Do not open the debug port to the public internet. Keep Xdebug disabled or restricted in production.

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

When a breakpoint is not hit, check the runtime first, then the network path, listener, and file mapping. A consistent interpreter and server mapping solve most PhpStorm/Xdebug setup issues.

Official documentation

Share this page Help other developers discover this resource.