Configure Xdebug for PHPStorm: PHP’s Built-In Server

PHPStorm is awesome. PHPStorm with Xdebug is even better. Specifically, when using Xdebug with the built-in PHP server. To Get Xdebug working in PHPStorm take these three steps:

1. Step 1: In PHPStorm set the Xdebug port to 9003 under Preferences | Languages & Frameworks | PHP | Debug. In older versions of Xdebug port 9000 was the default but that port conflicts with php-fpm. Port 9003 is what you will want.
2. Step 2: Install Xdebug if you don’t have it installed yet (macOS user install Xdebug and PHP using this guide).
3. Step 3: Ensure you have the proper Xdebug configuration in your php.ini file. Will will need at a minimum the following settings:

#### Xdebug 2 ####
xdebug.remote_autostart = 1
xdebug.remote_enable = 1
xdebug.idekey = PHPSTORM
xdebug.remote_host = 127.0.0.1

# Port 9000 is used by php-fpm. Use 9003 instead
xdebug.remote_port = 9003

Update: In Xdebug 3, several configuration settings were modernized and simplified, making your PHP debugging setup cleaner and easier to maintain. If you’re upgrading from Xdebug 2, here’s what you need to know:

• xdebug.remote_autostart = 1 → xdebug.start_with_request = yes
  Debugging now starts explicitly with incoming requests, replacing the old automatic start flag.
• xdebug.remote_enable = 1 → xdebug.mode = debug
  Instead of a simple on/off switch, Xdebug now uses modes, allowing you to enable only what you need.
• xdebug.remote_host = 127.0.0.1 → xdebug.client_host
  The setting for your debug client’s host has been renamed for clarity.
• xdebug.remote_port = 9000 → xdebug.client_port = 9003
  The default port changed from 9000 to 9003, so update your IDE settings accordingly.

These changes are part of Xdebug’s move to a cleaner, more intuitive configuration system, reducing guesswork and making debugging more predictable.

#### Xdebug 3 ####
xdebug.start_with_request = yes
xdebug.mode=debug
xdebug.client_host=localhost
xdebug.idekey = PHPSTORM

# Port 9000 is used by php-fpm. Use 9003 instead (new default)
xdebug.client_port=9003

Xdebug Port 9000 Conflicts

If you run into an issue running Xdebug via PHPStorm, or another IDE, when using the built-in PHP server on macOS, or Ubuntu, you might have a conflicting port 9000 with php-fpm.

You can check the 9000 port using the following command on:

sudo lsof -i tcp:9000

To check the port php-fpm occupies use the following command:

sudo lsof -i -n -P|grep php-fpm

Xdebug and php-fpm, or another service, might both be running on port 9000. The simple fix for this is to change the Xdebug port to 9003.

xdebug.remote_port = 9003

Then in PHPStorm set the Xdebug port to 9003 under Preferences | Languages & Frameworks | PHP | Debug.