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.


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.


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).


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.

Binary Data vim-xdebug.tar.gz10.77 KB


Tue, 2009/02/17 - 01:32

I spend a lot of time with the same error, but I fixed it when I realized that I have been written a wrong url, in my case with "??" like this:


I hope that helps...

Sun, 2009/12/06 - 20:46

In case this helps anyone else, you will need to add the following line to your php.ini file if it is not already there:

xdebug.remote_handler = dbgp

I finally got this working because of the three settings mentioned above.

xdebug.remote_enable = 1
xdebug.remote_port = 9000
xdebug.remote_host = localhost

Running with MAMP 1.9
(PHP 5.2)
(Mysql 5.1.44)

Mac OSX 10.6.4

Mac Vim 7.2

Many thanks!!!

Mon, 2008/05/19 - 14:19

May be you forgot XDEBUG_SESSION_START=1 in your url. Try the following formats immediately after pressing F5 in Vim.

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

Sat, 2008/10/11 - 08:59

Has anyone figured this one out?

I have the same exact line "1078" issue.
Ubuntu 8.0.4, Vim 71, XDEBUG 2.0 installed properly. Using the ?XDEBUG..START=1 just fine.

The connection/debugging works fine with Eclipse and with Spectator -- so everything in the pipe is "clean".

Why isn't this Vim capability working?

Thanks in advance,

Wed, 2009/03/04 - 09:38

I was having the same problem. Reasons for me:
. was using the old script not the Sam Ghods one http://www.vim.org/scripts/script.php?script_id=1929
. selinux was stopping httpd connecting back to port 9000 - solution - setsebool -P httpd_can_network_connect=1
. I just wasn't refreshing the page fast enough after hitting F5!

Testing using the xdebug debugclient helped make it clear if/when it was the script or something else.

Wed, 2009/12/09 - 22:31

How to know SELinux enabled:
check in apache error_log for the following statemetn
[notice] SELinux policy enabled; httpd running as context user_u:system_r:httpd_t:s0

Xdebug not getting loaded:

Failed loading /usr/lib64/php/modules/xdebug.so: /usr/lib64/php/modules/xdebug.so: cannot open shared object file: Permission denied
Failed loading /usr/lib64/php/modules/xdebug.so: /usr/lib64/php/modules/xdebug.so: cannot open shared object file: Permission denied
Failed loading /usr/lib64/php/modules/xdebug.so: /usr/lib64/php/modules/xdebug.so: cannot open shared object file: Permission denied

Command to be executed

$ getsebool -a|grep httpd_disable_trans
httpd_disable_trans --> off

$ setsebool -P httpd_disable_trans 1

$ getsebool -a|grep httpd_disable_trans
httpd_disable_trans --> on

Now restart the httpd again

Tue, 2009/05/19 - 09:32

This is a generic error message as far as I can tell -- it's an unhandled error when no connection occurs.

In general it means no debugging information is reaching the machine you're running vim on. This might be:
- a firewall
- forgetting to add XDEBUG_SESSION_START=1 to the URL
- your settings in php.ini (especially the xdebug.remote_* settings

So, ignore the message, think about why nothing is being sent to your port 9000 or why it is being blocked. Try telnetting locally to port 9000 while vim is listening -- this should result in a different error. If it does, you should try telnetting to your machine from a remote machine ... this will tell you if it's your firewall e.g.

Wed, 2008/11/12 - 12:49

I'm so freaking happy to have found this article. Interactive debugging was the only thing Eclipse had over vim for me--now I'm free from all the ponderous bloated Java GUI interaction forever.

Wed, 2010/05/26 - 11:11

Hi, first of all thanks for the post. It is really nice to be able to use xdebug inside vim. As others mentioned before I'm also using the newer version of the plugin written by Sam Ghods (http://www.vim.org/scripts/script.php?script_id=1929). I was having some problems with the original version that I don't have with the this one.

I would like to know if it is possible to use conditional breakpoint. I tried:

:Bp $var == "something"

But this doesn't work.

Thanks, Rodrigo.


Is your Drupal or Backdrop CMS site slow?
Is it suffering from server resources shortages?
Is it experiencing outages?
Contact us for Drupal or Backdrop CMS Performance Optimization and Tuning Consulting