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