HOW TO install Xdebug, php7, vagrant and Sublime3

I hate to install and configure it but overall it’s a great tool and a necessary one if you want to take debugging to the next level.

To stop var_dump-debugging you are going to need:

  1. A machine with IDE or PHP editor installed
  2. A server featuring Apache and PHP
  3. Xdebug package
  4. My configuration script
  5. Test it all

Let’s do it step by step.

1. Preparing PHP editor (Sublime3)

There are many tutorials for PHP Storm and Eclipse but very few about Sublime. That’s why I decided to focus on Sublime3.

2. Setting up a vagrant box

I’m basing this tutorial on a modified puphpet/ubuntu1604-x64 box.

Just clone or download this project:

or use any other favourite box.

3. Installing Xdebug

I’m basing the installation on the following bash script:


4. Semi-automatic configuration

Configuration is done by the bash script.

Ubuntu does not provide the correct version of Xdebug, that’s why I download and compile mine from source.

The configuration file is located in:

File content:

The most important think to know is to realise that Xdebug is actually working like a client, not a server!

Xdebug connects to your IDE/editor which acts like a server.

It seems confusing at first because Xdebug (a client) is a module for PHP (which is on server-side)  and it connect to your IDE which acts like a server (even though it’s normally considered to be on a client-side). It’s even more confusing because Xdebug plugin for Sublime is called ‚xdebug-client’…

If it’s not clear, please take a look at this diagram:


Let’s assume the following:

  1. IDE is installed on a machine with IP:
  2. Vagrant with Xdebug and PHP has IP:
  3. Xdebug client on has to connect to server – that is stored in 20-xdebug.ini file
  4. Sublime (or IDE) has to be able to connect to xdebug client on the vagrant box.

The last part is to tell Sublime to connect to the correct vagrant box. Here’s the sublime project file. It’s necessary to add path mapping and url for vagrant box.


5. Launch

Just install Xdebug plugin for Sublime and start debugging: Tool->Xdebug->start debugging.

Then place a couple of breakpoints in you code and go to:

Execution should stop at the first breakpoint.

6. Tips

I wasted a couple of days to get this setup working so, here are my mistakes. Don’t make the same ones 🙂

  • You shouldn’t redirect xdebug port 9000 in vagrantfile,
  • If you like port forwarding you can use it:

    The site will be then available at:
  • I’m using port 9001 to distinguish guest boxes from the host machine (which listens at :9000)
  • Think about working at multiple vagrant boxes simultaneously. You may want to use different ports or IPs or save those in your /etc/hosts
  • I like to use an additional conf.d/20-xdebug.ini file instead of opening and pasting stuff at the bottom of php.ini
  • Every time you change something in xdebug-php you need to restart apache
  • You do not need xdebug installed on you developer’s machine – just on tha vagrant guest box.

You must be logged in to post a comment.