To use PhpStorm with Ubuntu Vagrant install Xdebug for PHP

How the Vagrant box is configured

To be able to step through code using the IDE of our choice, we need to install Xdebug onto our Vagrant Box.

Good instructions here:

Updates to the Provisioning Script:

Install php5-dev php-pear using apt-get, install xdebug using pecl, creating a properly owned folder in /var/log to store the xdebug log file.

Added to apt-get packages list:

php5-dev #needed for xdebug
php-pear #needed for xdebug

Also added:

echo "Creating xdebug log directory: /var/log/xdebug"
mkdir /var/log/xdebug
echo "Changing xdebug log directory owner to www-data"
chown www-data:www-data /var/log/xdebug

echo "Installing xdebug"
pecl install xdebug

Needed to add the following to the php.ini to configure it for xdebug:

; Added to enable Xdebug ;
; use the following command to find
; find / -name '' 2> /dev/null
xdebug.default_enable = 1
xdebug.idekey = "vagrant"
xdebug.remote_enable = 1
xdebug.remote_autostart = 0
xdebug.remote_port = 9000
xdebug.remote_host= ; IDE-Environments IP, from vagrant box.

How to configure your IDE

Your IDE needs to listen for connections on port 9000.

Your IDE needs to know the host IP as well as the path the files reside in on the server.

Your IDE (or you, via a url) need to start and stop xdebug.

Configuring PHPStorm

Create Project

First, create a new project. If you’re using SVN, configure PhpStorm to use SVN and check out the project into a new folder.

Add Remote Server

File -> Settings

Under Project Settings [project-name] on the left, browse to PHP -> Servers

Click the green +



Port: 80

Debugger: Xdebug

Check “Use path mappings (select if the server is remote or symlinks are used)”

Under File/Directory on the left, Browse to Project Files -> checkoutdirwwwproject-name

Next to the www directory, on the right under Absolute path on the server, enter: /data/www (or wherever your files are stored on the vagrant box)

Click OK

Add Debug Config

Under the Run dropdown menu, click Edit Configurations…

Click PHP Web Application, then click the green +

Name: vagrant

Server: should be in the dropdown

Start URL: /

Browser: Chrome

Start Listening for Debug Connections

There’s a telephone icon in the icon bar, with a very small green bug and a red circle with a line through it.
Hovering over it, it will say Start Listen PHP Debug Connections
Clicking that will start the listener.


Click Run -> Start Listen PHP Debug Connections

Start Debugger

Make sure vagrant is selected in the drop-down next to the green play arrow icon in the header.

Click the green bug icon in the header (hover text is Debug ‘vagrant’ Shift+F9)


Click Run -> Debug vagrant

A new browser window will open with a url something like: “”

If you have a breakpoint defined, the browser will appear to ‘hang’ or ‘spin’ or ‘load’ forever. It’s waiting for the IDE to give it the go signal. Press F9 OR click Run -> Resume Program to finish loading the page.

Debugging / Stepping through the program execution

First off, you need to have a breakpoint set, or you will not stop program execution, and so will not have the opportunity to utilize the debugger.

Set a breakpoint by clicking in the left margin right next to the code to put a red dot there.

Now click a link on the application in the browser, and the server will execute all the code up to the red dot, and stop, waiting for a command.

Pressing F7 for Step into will make sure to execute every single line of code

Pressing F8 for Step over will go to the next line but basically never leave the current file: it will not dive down into function calls. This is useful for skipping stuff you know you don’t care about.

Stopping the Debugger


Run -> Stop, or

Clicking the red square in the debug window all stop the PhpStorm debugger.

However, if you click a link on the browser it will start right back up again. It needs to send a header to the xdebug server and… it doesn’t appear to. We can send that ourselves.

1) Click Stop

2) Follow this link:

3 thoughts on “To use PhpStorm with Ubuntu Vagrant install Xdebug for PHP

  1. Chris

    Thanks, this was indeed the only tutorial that actually made remote debugging within a vagrant box possible! The last half of the article wasn’t needed, as PHPStorm 7 makes most of this automatically.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.