Be part of JetBrains PHPverse 2026 on June 9 – a free online event bringing PHP devs worldwide together.

assertzero's avatar

SOLVED: Xdebug PhpStorm Homestead Breakpoint not hit - Path Mapping setup fix Mac

I have had a problem with Xdebug and breakpoints not being hit when using PhpStorm and Homestead 0.4.2 on my Mac OS X setup and wanted to share my configuration as to help others:

on your vagrant box, make sure to add the following lines to
/etc/php/7.0/mods-available/xdebug.ini

xdebug.remote_enable=1
xdebug.remote_connect_back=1

then restart the PHP service on Homestead with
sudo service php7.0-fpm restart

In PhpStorm go to Preferences, then Languages & Frameworks > PHP > Debug > Servers. There is only one path mapping you need to set to make it work. You have to map the file/directory root of your Laravel installation to the absolute path on the server.

In my case, Laravel is installed at
/Users/username/Projects/myproject
the corresponding mapping on my Vagrant Homestead box is
/home/vagrant/myproject

As you can see, this is the folder which contains the Laravel folder (as well as vendor, Vagrantfile, Homestead.yaml etc., not the Laravel folder itself.

My issue had been that I tried to only map index.php or the public directory within the Laravel folder. Turns out is important to map the parent or root folder of the Laravel installation.

Similarly, see this screenshot, where test is the parent folder of Laravel ( http://imgur.com/CrHEo0W )

This is the only mapping needed. With this setup, all breakpoints are reached.

Hope it helps someone!

0 likes
3 replies
marcusmoore's avatar

Thanks! I updated Homestead and ran into the same issue. I think xdebug.remote_connect_back=1 is the key here.

Just an FYI: I think I added remote_enable by itself a couple days ago and that didn't work.

assertzero's avatar

You have the alternative of using either xdebug.remote_connect_back=1 or use the xdebug.remote_host config option, but you must specify either of them. I find the connect back way more convenient.

My problem was that I had the path mappings wrong. PhpStorm suggests a mapping when first connecting, but that was just for the index.php file for me. I just didn't come up with mapping the folder surrounding the Laravel installation.

1 like
jtrod's avatar

Thanks. I was having trouble with that

Please or to participate in this conversation.