@KAndy’s answer put me on the right track, but I am developing locally using vagrant and had to do the following to get this to work1
Configure Xdebug:
zend_extension=xdebug.so
xdebug.remote_enable = 1
;remote_connect_back will fail because REMOTE_ADDR header won’t be set
xdebug.remote_connect_back = 1
xdebug.remote_autostart = 1
xdebug.idekey = "PHPSTORM"
;remote_host is ignored when remote_connect_back is enabled & successful; fallback
;Set to your HOST MACHINE IP
xdebug.remote_host=xx.xx.xx.xx
;provides valuable insight if you can’t connect. Remove when done.
xdebug.remote_log="/tmp/xdebug.log"
Set the remote_host
IP to the IP address of the host (for me, using the IP address from ifconfig
on the guest machine did not work - used IP address acquired from the network settings on the host machine as the remote_host
).
Configure PHP Storm
- Set up a server under
Settings -> Languages and Frameworks -> PHP -> Servers
if you have not done so already. (See screenshot)
Run -> Edit Configurations
and add a PHP Remote Debug.
- Choose the server you created in #1
- Set the IDE Key to PHPSTORM

- (Optional)
Settings -> Languages and Frameworks -> PHP -> Debug
Check "Break at first line in PHP Scripts" (this can help debug issues with your path mapping.)
Run -> Debug Vagrant
(or whatever you named your configuration in Step 2)
- Run the script you'd like to debug (
magento setup:upgrade
in my case)
1I'm using ubuntu/trusty64 for reference