How to Install Xdebug with PHPStorm and Vagrant

By Bruno Skvorc

Working with PHP 7.1? Download our FREE PHP 7.1 Cheat Sheet!

By now, we’ve all learned to love Vagrant and the development flexibility it provides. No matter the platform, you can easily have a development environment up and running in no time that’s not only stable, but also identical in every regard to the environment your colleagues, mentors or mentees use. But as the applications we’re developing reside inside a virtual machine, they’re a bit tricky to debug with Xdebug which is, by default, tuned for localhost.

Xdebug is a PHP extension which allows you to debug and profile your code, view detailed and readable stack traces when errors happen, and much more. For a detailed walkthrough, see Shameer’s post. If you’re completely unfamiliar with it, you would do well to first install it following the procedures below, and then refer to the post linked above for a breakdown of everything Xdebug can do for you and your apps.

In this tutorial, we’ll set up Xdebug with PHPStorm for Vagrant hosted PHP apps.


To prepare the environment, please install and boot Homestead.

Once it’s booted, vagrant ssh into it, and install a sample Laravel app. You can do this by executing:

composer create-project laravel/laravel Laravel --prefer-dist

When you get the Laravel greeting screen, you’re good to go.

Installing Xdebug

This step can be skipped. Homestead comes with Xdebug installed and enabled. You can see this by looking at phpinfo() after booting Homestead:

or by checking out the conf.d folders of PHP FPM and PHP CLI:

ls /etc/php5/fpm/conf.d
ls /etc/php5/cli/conf.d

If you see xdebug.ini in there, it’s loaded. If you’re using any other Vagrant box instead and xdebug isn’t present, refer to Shameer’s post for installation instructions.

Configuring xdebug.ini

To allow Xdebug to be used remotely, we need to alter the ini file and give it some parameters that are off by default. Homestead’s default xdebug.ini file (found in /etc/php5/mods-available) originally only contains the directive that tells PHP to enable it, but nothing else:

Under that line, add the following options:

xdebug.remote_enable = on
xdebug.remote_connect_back = on
xdebug.idekey = "vagrant"

Close the file and restart php-fpm: sudo service php5-fpm restart. That’s all we need to configure on Xdebug’s end.

Configuring PHPStorm – Servers

PHPStorm needs a bit of configuration, too. First, use it to open the directory of the Laravel app we created in step 1:

Then, go to project settings and under PHP -> Servers add a new one. Give it port 8000, the name of your choice, and under host, put the name of your site’s virtual host (default: Then, use Path Mappings to map paths so that the location of your codebase on the host machine corresponds to the location on the VM. Do the same for the public subfolder. Basically, transplant the folders block from Homestead.yaml to this window. Follow my example:

Configuring PHPStorm – Debug Configuration

To run the debugger on an app, we need to create a debug environment. Go into Run -> Edit Configurations. In there, create a new configuration for “PHP Web Application”:

Apply the new settings and close the configuration.


That’s all there is to setting it up. Let’s see if it works as expected.

In app/routes.php, alter the home route’s closure so that it looks like the code below:

Route::get('/', function()
    $a = [1, 2, 3, 4, 5];

	return View::make('hello');

Then, put a breakpoint next to each line of the closure that does something, like so:

Let’s test these breakpoints. If you have the app open in your browser, close that tab now, otherwise PHPStorm won’t be able to re-run it. Then, go to Run -> Debug and run your predefined debug configuration. A new tab should launch and immediately return you to PHPStorm with an output similar to this one:

The left frame lists the stacktrace – the files the request already went through – and stops at routes.php, our file. You’ll notice in the right panel that only the superglobals are declared – no other variables are present at this time. Clicking the Resume button moves on to the next breakpoint and produces the following output:

Notice our $a variable is there now. Also notice you can expand it to see what it contains. Clicking the Resume button once more produces a slightly different output:

Our $a array has one less element due to the array_pop operation we performed. This proves our breakpoints work as intended, and Xdebug has been successfully set up.


Despite initial impressions, Xdebug is very easy to install for use via Vagrant when one knows what has to be done. These instructions are easily applicable to Xdebug’s integration into any other IDE as well, so feel free to adapt them as you see fit – only the PHPStorm sections likely need changing.

Do you debug through the VM layer? Are you using any other approaches? Have any problems we neglected to mention? Let us know!

  • I have done a little bit different :) I’ve been looking for solution a couple of weeks ago. You can find the result at

  • Have you ever tried Vaprobash? Its greaet and it comes with xdebug preinstalled, all works out of the box and you dont mess with your computer since you are using Vagrant

  • Of course, but you don’t mess with your computer in this example either. It also uses Vagrant. The XDebug enabling is the same with Vaprobash as it is here.

    • Agree on that, your article covers more of that not just only installing XDebug, great article Bruno, keep up the good work!

  • Nice article. I’ve just created a blog post with an additional Cli Debugging mode:

  • Alexey Bakulin

    I use for debugging Remote debug in PHPStorm and little plugin for Google chrome called Xdebug helper.

    • Diego Ruiz

      same, it’s immensely helpful

  • PhillipMobbs

    Just a heads-up, the install and boot homestead link is broken, its being treating as a relative.

  • Will Melbourne

    hi have you managed to get this to work to debug scripts called from the command line? I haven’t been able to get PHPStorm to pick those up.

    • Example?

      • Will Melbourne

        Hi Bruno. I mean if you are running PHP from the terminal, we have a lot of batch jobs and sysadmin tasks running from the terminal and when I posted this question I thought it would be helpful to run xdebug to see what is going on. Now I have been using xdebug longer I am under the impression that xdebug sets a cookie in the browser and works with that so terminal debugging isn’t possible. There are ways around this such as running batch scripts from the browser and using xdebug then but I was curious if anyone had xdebug running directly from the command line

        • Will Melbourne

          although I just noticed @Adam Balogh looks like he has solved this problem. Note I haven’t had time at work to test his solution but looks like what I was wondering about.

  • asdasdasdasd

    bullshit “how to install Xdebug”, yeah, for laravel with homestead…and without homestad/laravel????

    • Bruno Škvorc

      For generic instructions, see their README file. But if you’re using any kind of linux distro for development, the procedure is almost identical.

  • Brian

    Bruno, thank you for explaining the Server Path Mapping details for both the root and public directories. Configuring this step properly enabled me to remote debug successfully!

  • Christian

    Thanks, finally have xdebug working in PHPStorm with Homestead! The browser does eventually timeout with a 504 gateway time-out from nginx. Any fix for that?

  • Дмитрий Кабардинов

    strangely, it worked. Although I use custom ubuntu on virtualbox instead of vagrant. Usually this kind of guides don’t do me any good, but that’s not the case. Thanks a lot.

  • ArafatX

    I got a message “waiting for incoming connection with ide ‘10008’. I followed the exact same procedure.

    • ArafatX

      It’s ok I fixed it. I put the wrong mapping path.

  • Leszek Pietrzak

    Thx, works like a charm with PhpStorm 9

  • Ayelen Guerra

    Thanks Bruno!

  • Pedro Izaguirre

    This was really helpful I love Homestead and this help me resolve my issue with Xdebug

  • Benjamin Ellis

    Thx for the post! I have this issue :

    Waiting for incoming connection with ide key ‘12080’. I checked my mapping path, all OK as homestead.yaml. I’m working with windows 8.1. Any idea? :(

    • Did you follow all the steps exactly? Seems to work for everyone else. I’m afraid I no longer have 8.1 so I can’t test.

  • Benjamin Ellis

    Thx for the post! I have this issue :

    Waiting for incoming connection with ide key ‘12080’. I checked my mapping path, all OK as homestead.yaml. I’m working with windows 8.1. Any idea? :(

  • Mathew

    I got a message “waiting for incoming connection with ide ‘19404’. I followed the exact same procedure. and try with all available option from google but couldn’t find any success.. anyone please help

  • Mathew

    I got a message “waiting for incoming connection with ide ‘19404’. I followed the exact same procedure. and try with all available option from google but couldn’t find any success.. anyone please help

  • Edys Meza

    Great Post!

  • Cristiano Pacheco

    Hello, thank you!
    this tutorial has been really great help to me.

Get the latest in PHP, once a week, for free.