Using Xdebug in PhpStorm with a Vagrant VM managed with PuPHPet

Installation and configuration

In PuPHPet configuration file config.yaml

  • make sure Xdebug is enabled (install: '1')
  • set xdebug.remote_connect_back to 0
  • add xdebug.remote_host. Set it to
    install: '1'
        xdebug.default_enable: '1'
        xdebug.remote_autostart: '0'
        xdebug.remote_connect_back: '0'
        xdebug.remote_enable: '1'
        xdebug.remote_handler: dbgp
        xdebug.remote_port: '9000'
        xdebug.remote_host: ''
  • run vagrant provision

In PhpStorm

  • Open your project
  • In the menu Run, select Start Listening For PHP Debug Connections

In a browser

  • On the PhpStorm bookmarklets generator page, under Xdebug, click the Generate button and drag the Start debugger and Stop debugger links to your browser's bookmarks toolbar.
  • Go to the root page of your web application
  • Click Start debugger in your bookmarks toolbar.

In PhpStorm

  • A window similar to this one should have appeared:

  • Click Accept.
  • If this index.php file is in a public subfolder of your web application, you need to adjust the root folder for Xdebug. In the menu PHPStorm -> Preferences... -> Languages and Frameworks -> PHP -> Servers, add a Absolute path on the server value for your project root (you can remove the value for the public folder):

Note: make sure to use /var/www/<your project folder>, not /vagrant/<your project folder>

Use it

In PhpStorm

  • in one of your project files, add a breakpoint.

  • In the menu Run, make sure Start Listening For PHP Debug Connections is selected

In your browser

  • go the corresponding page of your web application
  • Click Start debugger in your bookmarks toolbar.
  • Reload the page
  • Back in PHPStorm, the debugging information should appear in the bottom panel.

  • Click the Resume button (green triange on the top left) to leave the breakpoint and resume the normal execution.

How it works

The bookmarklets add/remove the cookie XDEBUG_SESSION for the current website. That cookie makes the Xdebug PHP module communicate with PHPStorm, which is listening on port 9000. The host machine is accessible from the VM at



This line saved my week :-)

xdebug.remote_host: ''

Jul 21, 2017