Remote debugging with vim and xdebug

A while back I posted on twitter that I had figured out how to use xdebug & vim and promised to do a blog post on how I got it all working. This is that blog post. Before we can get started using Vim to remote debug PHP code, we’ll need to do a few things.

Install things

Install xdebug. If you haven’t done so already, you can install xdebug with sudo pecl install xdebug. Remember to restart your webserver when you’re done or xdebug won’t work. Next, get vim up & running. If you aren’t using vim, and have always wanted to, now is a great time. I recommend using my vim-files repository. It will save you some time finding good plugins as I’ve already done the leg work. Next you will have to install VDebug. I use pathogen to manage my vim configuration.

Is all that is needed to get Vdebug installed in a pathogen based vim setup.

Configuration

Now you’ll need to configure both xdebug and Vdebug so they know where to talk to each other. Xdebug uses the dbgp protocol for debugging which makes a connection on port 9000 by default. We’ll need to tell both xdebug & vdebug a bit about the other so they can work.

Configure xdebug

You can use phpinfo(); to find out where your php.ini file is. Once you’ve found where your php.ini file is located, add the following to it:

The above enables remote hosts to start debugging sessions on your webserver. If you are not connecting on localhost, you should set xdebug.remote_host to the value of the host that is running Vim. Remember to restart your webserver after modifying the ini files, or the changes won’t take effect.

Configure Vdebug

Vdebug takes its configuration options from variables defined in your vimrc. A sample configuration would look like:

The most interesting configuration option is the path_maps key. This is extremely useful when debugging files that are on another machine. On the lefthand side are file paths on the remote machine. On the right hand side are the same file paths on the machine running vim. This configuration allows Vdebug to find the files on your machine that match the ones on the remote server. If you’re only running things on localhost you won’t need path mappings, as they will always be the same. The server configuration value tells Vdebug to listen on all interfaces which makes life a bit easier.

Using Vdebug

Once all the configuration is done, you should be able to press <F5> in Vim to start a debugging session. Quickly reload the page/run the script you want to debug. If you did everything correctly a new tab will open with the various debugging panes displayed. You should see something like:

On the left is the code the server is running. With a sign pointing at the current line. In the top right panel are the current values of all local, global, and superglobal variables. You can open and close nested structures with <Enter>. In the middle right is the current call stack. Pressing <Enter> on any line will show that file in the code window. The bottom right panel shows the debugger status, and whether or not the debugger is active or not.

You can set breakpoints with :Breakpoint, and move through lines with <F2>, <F3>, and <F4>. There are a number of other keybindings you can use and the help for Vdebug is excellent, and well worth reading. You should be ready to do any debugging you need from here on in, all without needing to leave vim.