Bill Shupp Software engineer, photographer, musician, space geek


PHP step debugging in VIM

When debugging problems in PHP, most of the time it's easiest to just add var_dump($foo); exit; in the middle of your script, and you can see the contents of $foo right in your browser.  But if you have to do much more, this approach gets cumbersome pretty quickly.  I've recently been using step debugging for harder to track down problems.  It allows me to examine the state of things all the way through execution of a request, line by line, or skipping ahead to break points.  This process also gives you more insight into everything else happening in a request, which can be useful when you're using frameworks or other 3rd party code in your application.

With PHP, the common extension for this is Xdebug.  (See the remote debugging documentation here).  Since my main text editor is VIM, I had to find a suitable plugin to talk to Xdebug.  It turns out there are a few good blog posts already on this topic, so I won't duplicate the information here.  This post does a great job of covering installation and usage of the Xdebug plugin for VIM by Seng Woo Shin, though it links to an older version of it.  Here's a link to a newer one that Xdebug also links to.  The Xdebug site links to another tutorial that's worth a read too.

Beyond the links above, I've discovered a couple of things that are worth sharing.  First, there's a new FireFox extension, easy Xdebug, that is a real lifesaver.  You just click the green bug on the bottom right, and it will try to start an Xdebug session with any request (rather than having to add XDEBUG_SESSION_START=1 to the query string parameters myself).  This is particularly handy when dealing with POST or or AJAX requests.  The Xdebug docs also link to similar tools for Chrome, Safari, and Opera.

Now, my debugging work flow looks like this:

  • Start the Xdebug session in FF by clicking the green bug
  • Set breakpoints in VIM
  • Press F5 in VIM to start listening for the request (it waits 5 seconds)
  • Perform that action I want to debug in FF
  • Press enter in VIM to enter the debug session
  • Debug
  • Press F6 to exit debugger, and fix the problem

The one gotcha that I keep running into is how to set breakpoints correctly.  When you use this VIM plugin, you must put a breakpoint on executable code.  If you put it on a blank line, or even on a line with just an opening try statement, your breakpoint will not work.  Instead, you'll end up with an "error 5".  This topic is briefly covered here and here.

Now, when I find myself using more than one or two var_dump() statements to debug something, I usually walk through the work flow above, and have things sorted out much more quickly than I used to.


UPDATE: There is a new VIM plugin that's much better for step debugging.  Check out the announcement here:

Filed under: Code, PHP, VIM, Xdebug Leave a comment
Comments (6) Trackbacks (1)
  1. As much as I tried to like PHP debugging in vim – I simply can’t. Trying to get some deep value from an array or an object is just a nightmare.

  2. Thanks for reading, and sorry you didn’t get any value out of it. Inspecting variable contents is of course only one thing you can do while step debugging. I also find it to be really handy for tracing the logic path through large amounts of code, and can be much more efficient than guessing at where to add var_dumps. But to each their own!

  3. Thanks for the info. I’m using vim and got it almost working. I keep getting the “error 5″ you mention even though I put breakpoints on executable code. Am I doing something wrong? I looked over the and debugger.vim files, but don’t see anything obviously wrong. Not sure where else to look to debug this. Any help or ideas would be greatly appreciated. Thanks!

    This is what I do:

    1) startup vim
    2) press
    3) refresh my working localhost page with ?XDEBUG_SESSION_START=1
    4) connection made between site and xdebug
    5) first line of index.php highlighted red
    6) proceed to put a breakpoint on the 3rd executable line of code in index.php using :Bp
    7) breakpoint line of code is highlighted green
    8) press to do a step_into – It works perfect!
    9) press to continue to the next breakpoint, which is 2 executable lines down – FAIL!

    My error message is:
    send =====> run -i 8
    recv <===== {{{

    send =====> stack_get -i 9
    recv <===== {{{

    response xmlns:xdebug=”” xmlns=urn:debugger_protocol_v1 command=stack_get transaction_id=9
    error code=5 : Command not available (Is used for async commands. For instance if the engine is in state “run” than only “berak” and “status” are available).
    command is not available

  4. The error code=5: “Command not available”… will happen if you try to run a command when the debugger has finished. It’s a bit wonky, and I haven’t tried to debug the script. I did just verify that adding multiple breakpoints and stepping into the first one, then hitting F5 will successfully continue down to the second one. But if I hit F5 again to continue, I’ll get the error code above when the page load finishes.

    So my guess is that your second breakpoint may be on code which doesn’t work with a breakpoint, even if it looks executable. I’d try some other spots.

  5. You were right, not everything that looks executable is.

  6. I suggest to use Codelobster ( for debugging PHP scripts.

Leave a comment