Using vim and xdebug DBGp for debugging Drupal (or any PHP application)

Update 2017-April-20: The information in this article contains a now outdated extension for VIM. In order to use a more current extension, please get vdebug, which works with XDebug.

Original article follows ...

The power and simplicity of some tools is often overlooked or underestimated.
One such tool is good old vim (VI iMproved), a text editor for UNIX systems, also available for other platforms.

This articles describes how vim can be used with the xdebug protocol to provide full debugging capabilities for Drupal (or any PHP application for that matter).

Please note that other IDE's for PHP handle debugging, such as Komodo, and even Quanta Plus for KDE (Linux). However, to have this power from a text interface is very cool to say the least.

Credits

The xdebug interface for vim was written by Seung Woo Shin and is available on vim.org. A slightly modified version with a README file is attached to this article.

Requirements

To use this script, you have to get python 2.3 or higher, and xdebug 2.0 on your system (we will cover the installation an configuration of xdebug in a future article).

Installation

Extract the debugger.py and debugger.vim files and place them in your .vim/plugin directory (create it if it does not exist).

Starting the debugger

Start vim, and hit F5. A message will appear waiting for a debug session to start and attach to your vim instance.Now, browse to the URL of the page causing you grief, and add XDEBUG_SESSION_START to the end of the URL.

For clean URLs use: http://example.com/admin/feature?XDEBUG_SESSION_START=1 Otherwise use: http://example.com?q=admin/feature&XDEBUG_SESSION_START=1
The debugger will start and several windows will appear in vim, with Drupal's index.php showing.

Here is how the start of a debug session looks:

Setting breakpoints

Using the :e command in vim, open the file you are interested in (e.g. feature.module in this case).Go to the function/line you suspect, and set a breakpoint using the :Bp command.

Here is how setting a breakpoint looks like:

Debugging at a breakpoint

Hit F4 to continue until the breakpoint is reached.

Reaching a breakpoints:

Once at the breakpoint, you can step through the program, display variables, ...etc.
Use the function keys and commands on screen.

Displaying variables

You can move the cursor to any variable, and hit F12 to see what is in this variable.

Displaying a variable:

Evaluating an expression or variable

Use the ,e command to evaluate an expression or print a variable. This is handy in complex variables such as objects and arrays.

Evaluating a variable:

Of course, there are many more uses for this, such as seeing how Drupal handles things, and how elegant its internal architecture is.

Desired functionality

vim xdebug is very powerful yet simple. It is missing only one feature, which is multi-user support. This requires the xdebug proxy to be supported. This allows multiple sessions to connect to the proxy with a different IDE Key (the argument for XDEBUG_SESSION_START).

If someone adds that feature before I do, let me know. I have the setup to test this if needed.