A common issue with a fresh installed OS and development software stack is that all three tools (Xdebug, PhpStorm, PHP-FPM) have their default port set to 9000.

This will cause some errors (down below / at the end of article) while trying to debug in PhpStorm.

The most simple (and fast) fix is to change the port of PHP-FPM from 9000 to another (9001?).

Recommended is to keep Xdebug and PhpStorm on 9000 and put PHP-FPM to 9001 or following consecutive ports.

I will explain how to change the port for all 3 tools.

The location for the config files differs from system to system, but the filenames should be similar.

  • The filename for the PHP-FPM normally is www.conf
  • The filename for the Xdebug is actually a PHP ini file and normally is xdebug.ini. But on some systems the settings could be inside php.ini.

The part in the files where you can change the port should be:

  • For PHP-FPM’s www.conffile you need to search for lines:
    ; The address on which to accept FastCGI requests.
    listen = 127.0.0.1:9000
    And change the port from 9000to 9001.
  • For Xdebug’s .ini file you need to either search for the following line, or add the line if not exists:
    xdebug.remote_port="9000"
    If you follow my recommendation you normally should let the default port as 9000, or change it to what you want.

For PhpStorm, you can change the port that connects with Xdebug from Preferences -> Languages & Frameworks -> PHP -> Debug -> Xdebug -> Debug port.

Be aware that PHP-FPM normally works with a web server (like nginx). If so, you need to change the port for PHP-FPM in the webserver too.

Now, for the errors that will appear if you have all 3 set to the same port (and PHP-FPM service started).

  • Connection was not established. Cannot start debugger session with ‘Xdebug’
  • Connection was not established. ‘Xdebug’ extension is installed. Check configuration options.

If you have any other issues with PhpStorm + Xdebug or PHP-FPM + nginx, feel free to ask in the comments below.

Happy coding!