sponsor Vim development Vim logo Vim Book Ad

XDebug (DBGp) client (for PHP) : minimal php debug client for XDebug (DBGp)

 script karma  Rating 33/12, Downloaded by 2365  Comments, bugs, improvements  Vim wiki

created by
Timothy Madden
script type
This is a modification of vimscript #1929 (DBGp client for PHP, which in turn is based on vimscript#1152 - remote PHP debugger) to make it work on Windows too. See that script for a link to a (Linux) tutorial on using vim to debug php. Or just keep reading this page.

You can see the the link to the wiki page above for an introduction to the concept model involved in debugging php pages.
A couple of screen-shots are available here: http://code.google.com/p/dbgp-client/wiki/screenshots
A page with setup instructions is available at http://code.google.com/p/dbgp-client/wiki/setup

With this script you should be able to perform simple (minimal) debugging steps into a php web page or a php command line script (actually the php script may also be a GUI application, not necessarily command-line) Note that there are a number of DBGp clients out there with more features (see a list at http://xdebug.org/docs/remote), but you might want this script if you want to debug from Vim. You might also find vim scripts similar to this one (for example vimscript #3320, search Vim scripts for "XDebug" or "php debug" to find them) but I do not know how good they are or if they work on both Windows and Linux.

Now to clarify: DBGp is the protocol for communication between a debug server (the debugger engine) and a debug client (the user interface with the opened source files and breakpoint markers on the proper lines). It is suited for remote debugging of your scripts, but it is the same mechanism used for debugging scripts locally also. The XDebug php extension is the debugger engine, that implements DBGp in php. This vim script is the debugger client that implements DBGp for Vim. Note that in this case the server initiates a new connection with the client, and not the other way around as one might expect.

You need to have XDebug extension installed and enabled in php (check the output of `php -m`), in order for php to work as a debug server and start a debugging session (see the XDebug documentation at http://xdebug.org/docs/). This script will only turn Vim into the debug client. You will need python2 installed (http://www.python.org/download/, not tested with python3) and Vim with +python and +signs features (most Vim distributions have them, see :version command). The default 'nopaste' option in Vim should be in effect, for expression evaluation in the debugger to work as expected. Some people like to copy/paste text, like samples of code for example, and for this they like to set 'paste' option in Vim (also because Vim feels more Windows-compatible with it), but unfortunately that will disable insert-mode mappings, that are used by the plugin. You can just set 'nopaste' during debugging, and set 'paste' back on after if you want.

To debug web pages, you may want to install the XDebug extension for Firefox / Chrome / Safari / Opera (maybe others?), or else you will need to manually add an XDEBUG_SESSSION_START query parameter to the page URL in order to start the debug session (but to submit a form and debug the referred page using a manual URL parameter, you will need quite some extra work).

With the browser extension installed, you should:
      1. Enable web page debugging from the browser with the toolbar button provided by the extension.
          This will tell php to start a debugging session on the next page, and than open a connection to the debug client.
      2. Press <F5> - Start/Continue debugging (by default) in Vim. Vim will now wait for the new connection from the server.
      3. Immediately reload or access the web page to be debugged (currently within 5 seconds since you start debugging in Vim).

For command line scripts, XDebug expects the XDEBUG_CONFIG environment variable to be set before php is invoked, in order to start a debugging session (and connect to the debug client). On a bash/sh shell (including cygwin/mingw if on Windows), the command line would look like:
              XDEBUG_CONFIG="ide-key=vim"    php     ../path/to/script-file.php   script-args....
On a plain cmd.exe console window on Windows you would need separate commands:
              Set XDEBUG_CONFIG=ide-key=vim
              php  ../path/to/script-file.php   script-args...
Again, you should press <F5> (by default) in Vim immediately before executing the above php command.

If you have some stubborn firewall, you should also make sure Vim is allowed to listen and receive connections on the debugging port (default 9000).

You might try the script with other debuggers than php, that implement the DBGp protocol (protocol specifications can be found on XDebug web site at http://xdebug.org/docs-dbgp.php), but it has only been tested with php (that is, with XDebug). If you do, you may leave the script author a message about it.

Currently the script still has a few bugs, is missing a documentation file (but it will display a shortcuts window once debugging is started), and only supports simple debugging commands. Once a debugging session is started, you may evaluate php expressions, including function calls, with the ,e (a comma and the letter e) keyboard shortcut. Note that XDebug (DBGp) has a "starting" state when your script is not being debugged yet (is not started) but the debugging session is started (just use step in/step over to enter your script), and a similar "stopping" state when your script has finished, but the debugging session is still active (for collecting certain statistics and other information, use <F6> - stop debugging to end the debugging session). The web browser will keep loading the page (will show the loading indicator) until you finish the debugging session.

In general different debuggers use different keys for debugging functions. This script will map by default almost all function keys F1 to F12 for debugging functions. However you most likely already have other mappings for some of these (or you may have plug-in scripts that have other mappings for some of these), so you should set the global option g:debuggerMapDefaultKeys in your ~/.vimrc file to one of these values:
     0 - disable default key mappings (use when you set your own mappings in ~/.vimrc for the debugging functions, recommended)
     1 - map  <F1> to <F12> keys
     2 - map <M-F1>..<M-F12> In this case <M-F4> (or Alt+F4) is also mapped to <M-C-F4>
     3 - map <S-F1>..<S-F12>
     4 - map <C-F1>..<C-F12>
     5 - map <M-C-F1..12>
     6 - map <M-S-F1..12>
     7 - map <C-S-F1..12>

For example to use Alt+Ctrl+F1 to Alt+Ctrl+F12 for debugging, write the following line in ~/.vimrc (or ~/_vimrc on Windows)
     let g:debuggerMapDefaultKeys = 5
On Linux however the Alt+Ctrl+F1.. keys are used to switch virtual consoles. So beware that Vim may not be able to sense all of these key combinations on all systems, so you may need to try more than one set of them before you choose one. Also, if you change this option, note that the shortcuts window in the debugger will still display <F1>,...<F12> as the debugging keys...

Another known problem is that the script does not properly save/restore Vim windows for multiple tabs before and after a debugging session (it tries to use the :mksession and :source commands for this purpose) and as such it is currently recommended that you start a new Vim instance before debugging, or to use a single tab in your (existing) vim session.

If you would like to submit patches or you have modifications to the script, you can send them to the author.

When debugging files on a remote web server (not the local host) you can not currently open the source files being debugged, so this is not supported yet. One way around this problem is to use symlinks on your computer so that the file paths on the server match the file paths on the client. It is possible to modify the script so as to include a user mapping for remote files to local files (if you have an exact copy of the source files on the local computer) or to some other remote protocol (if you can open the remote files through FTP / HTTP / VPN / SSH / network shares...).

The project source code repository and issue tracker can be found at: http://code.google.com/p/dbgp-client/
You are welcome to use the tracker there for suggestions or issues that you may have.
install details
Unpack the .zip archive into the directory:

    %USERPROFILE%\vimfiles                 (on Windows)
    $HOME/.vim                                         (on Linux/Unix/...)

The %USERPROFILE% directory on Windows is usually:
         C:\Documents and Settings\_User_Name\

You may also use the system plugin directory for vim on your system if you want to install for all users.

This will just install the two files debugger.vim and debugger.py (no documentation file included) and will directly map the <F5> key to start a debugging session (or continue running the debugged script), and also a few other keys for debugging (F2, F3, F4 - step into, step over, step out;  <F11> - get list of script variables in the current context).

You may wish to map <C-M-Up> and <C-M-Down> keys (Alt+Ctrl+Up-Arrow, Alt+Ctrl+Down-Arrorw) to the :Up and :Dn commands, to navigate the call stack of your php script with them. However the eval ,e command may only use variables from the innermost (nested) stack frame.

As mentioned above you need python2, php with XDebug extension, Vim with +python  and +signs features (and the default 'nopaste' option) and the browser extension (plug-in) for XDebug.

rate this script Life Changing Helpful Unfulfilling 
script versions (upload new version)

Click on the package to download.

package script version date Vim version user release notes
debugger.zip 0.55 2012-04-13 6.0 Timothy Madden Added option to disable/change default key mappings
debugger.zip 0.51 2012-04-10 6.0 Timothy Madden Added a short status line message if python can not be loaded, since many new Windows users are likely not to have it.
debugger.zip 0.5 2012-04-09 6.0 Timothy Madden Initial upload
ip used for rating:

If you have questions or remarks about this site, visit the vimonline development pages. Please use this site responsibly.
Questions about Vim should go to the maillist. Help Bram help Uganda.