Xdebug issues on macOS

Recently I spend a lot of time trying to configure Xdebug on my local machine. I am working on macOS Mojave with PhpStorm.

The standard installation guide from JetBrains is a really good start and works 99% of the time. But this time I could not get it to work at all.

The problem

Whenever I started the debug button, the debugger would never hit any breakpoint in my code. I was getting the following error:

Connection with Xdebug 2.6.1 was not established.
Xdebug 2.6.1 extension is installed. Check configuration options. 

The solution

After troubleshooting the issue and a lot of Googling, I checked which other processes were listening to the port 9000.

sudo lsof -iTCP -sTCP:LISTEN -n -P

It turned out the php-fpm was listening to port 9000 and was receiving the debug connections from my editor. It turned out that I had installed php with php-fpm via brew and brew had configure the php service as autostart.

Stopping the brew php service fixed the issue.

brew services stop php           

Happy debugging!