Remote Debugging PHP with VIM and XDebug

Many php developers enjoy outputting debugging information using functions such as var_dump during the development process, but sometimes it’s not effective if the program logic is complex or if you want to step through code line by line. To console debugging information, we have to manually add debug statements in our code, this is really a waste of time. Fortunately, there is a useful php extension called XDebug which provides debugging, profiling, tracing and code coverage support. With the debugging ability of XDebug, we could add breakpoints, watch variables and examine the call stack in our php code, just like IDEs for other languages such as java.

Now I have a local machine (debugger client) that runs Mac OS X 10.8 and a virtual machine (php + web server) that is running Ubuntu Server 12.04 operating system as a remote server in Oracle VM VirtualBox. In the virtual machine, there is a php web application. In this article, you’ll see how to install and configure XDebug, and how to debug the php application using VIM on a local machine.

The picture below describes the theory of remote debugging with xdebug.

theory about remote debuging with xdebug

In order that the local machine and remote server could access each other, I create a host-only network with virtualbox, the local machine could visit the site on the remote server through address, and the remote server could access the local machine through ip About setting host-only network in virtualbox, you can visit this article Host-Only Networking With VirtualBox.

Install XDebug in Remote Server

  • First download xdebug source files, then compile it to .so extension. Before compiling, make sure you have installed php5-dev package, if not, Debian users can install it by typing command:
    $ sudo install php5-dev
  • Compile xdebug.
    # run phpize, use phpize in your own environment instead.
    $ /usr/bin/phpize
    # remember use the path of php-config in your own environment.
    $ ./configure --enable-xdebug –with-php-config=/usr/bin/php-config
    # copy to php extensions directory
    $ sudo cp modules/ /usr/lib/php5/20090626/
  • Edit the php configuration file php.ini, it’s located at /etc/php5/cli in my remote server. Then add these lines to php.ini.
  • [xdebug]
    ; The port to which xdebug tries to connect on the remote host.
    ; The host where the debugger client is running, is the ip address
    ; of the debugger client machine.
  • Restart the web server. To check whether xdebug extension takes effect, you could create a phpinfo page, and see whether the xdebug extension information appears on the page result.

    xdebug infomation in phpinfo page

Configure VDebug in VIM

In the local machine (debugger client), I will add a plugin called vdebug to the vim editor. Vdebug is a new, fast, powerful debugger client for Vim, it interfaces with any debugger that faithfully uses the DBGP protocol, including xdebug for PHP. One important issue to note is that the vim must have tabs, signs, python support and the version of python should be 2.6+.

  • Download vdebug and uncompress the pachage, then copy its content to your ~/.vim/ directory.

    For more installation methods about vdebug, please refer to README of vdebug.

  • Configure options for vdebug. You need set the port to which the xdebug connects, edit file ~/.vimrc, add these lines:
    let g:vdebug_options = {}
    let g:vdebug_options["port"] = 9000
  • Map code paths. To use xdebug remote debugging, a same copy of the php files in the remote server should already exist in the local machine. Although the php application runs in the remote server, but if you want to debug php files in local vim editor, the vim needs display the sames files for you. For example, the path of the php source files on my remote server is /var/www, and the I have the same code files in the directory /Users/ccpalettes/php/xdebug on my local machine. So I append the lines below to file ~/.vimrc.
  • let g:vdebug_options["path_maps"] = {
    \    "/var/www": "/Users/ccpalettes/php/xdebug"

How to Use

As I mentioned earlier, I could access the php web application through on my local machine. Follow these steps below, I could debug php files easily.

  • Open the php file that you want to debug in vim.
  • Put the cursor over the line to which you want to add a breakpoint, press F10, you can see the line will be highlighted which indicates a breakpoint has been set. To remove the breakpoint, just repeat the action on the same line.

    add a breakpoint

  • Then press F5 to start the debugger, a message will be shown at the bottom of the vim editor.debugger start message
  • Open your browser on the local machine, input the url of the web application ( into the address bar and append ?XDEBUG_SESSION_START=1 to the end of the url. Finally, the url will be concatenated into Parameter XDEBUG_SESSION_START will be saved in the cookie in your browser which tells the xdebug to make a connection with the debugging client.
  • After refreshing the page, the xdebug should work now, and you will able to see source, watch, stack and status window in the vim.

    debugger windows

Here are a few available commands in vdebug. You can see more details in vdebug document.

Run               <F5>
Step over         <F2>
Step in           <F3>
Step out          <F4>
Run to cursor     <F9>
Detach            <F7>
Stop/close        <F6>

Debugging in local environment

Although I am talking about remote debugging php, but these steps also could be applied to local debugging. The only difference is that the remote server and the debugger client are actually the same machine. The image below show how the xdebug works under local environment.

remote debugging php in local environment

One more note

XDebug is powerful, it provide you not only the debugging ability, but also a lot of features waiting to be discovered by yourself.


3 thoughts on “Remote Debugging PHP with VIM and XDebug

  1. Pingback: José Francisco da Silva IV » Debugando remotamente em PHP usando Vim e Xdebug.

  2. Pingback: Debugging PHP in Ubuntu (Xdebug) | Ubuntu InfoUbuntu Info

  3. Pingback: Débugger PHP en CLI avec Xdebug & Vim | Octopuce

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s