Shell Notes: Vim XDEBUG

Continuing my deep dive into shell and editor commands to find, useful tools that I’m not taking full advantage. This week is debugging PHP using Vim and XDEBUG.

XDebug in Vim

XDebug has been installed on every development machine that I’ve worked on for as long as I’ve worked. It outputs wonderfully formatted stacktraces and var_dump values. However, the interactive debugger side of XDebug remains little used due to the overhead of setting it up.

When I developed using PHPStorm, the interactive debugger seemed extraordinarily unstable. After taking the time to set up a project, map the directories correctly, configure ports and then trigger the debugger it would run for a few lines then halt. I eventually stopped using it.

The Vim VDebug plugin, running locally on the server seems a much more stable implementation. However, I still use it much less often then I should. Largely, this is due to comfort level. I’m not comfortable enough with it, so I don’t bother triggering it.

Yet, it would be easy to become comfortable. Any time that I want to inspect the value of a variable under an operations, instead of echoing or var_dumping that value out – put a breakpoint, and trigger the debugger. After a while, it will become like second nature to enter the debugger instead of printing the variable. Consequentially, if after inspecting the first variable, I discover the need to inspect a second variable, well the debugger has already started and inspecting the second variable is a zero-cost operation.

Installing and configuring XDebug, I leave to the documentation. Initiating the interactive debugger is done through VDebug, a Vim plugin that works with PHP, Python, Ruby, Perl, and NodeJS debuggers – or as it’s documentation says, any debugger that implements the DBGp standard.

Starting the XDebug Plugin:

Debugging starts by selecting a breakpoint line, navigating to it and pressing <F10> to toggle the breakpoint. Second, we start the debugging session by pressing <F5>. We then have 30 seconds to start the session which can be done in one or two ways.

If accessing our PHP script via the browser, we add XDEBUG_SESSION_START=$ideKey to the URL query string. If accessing our script via the commadn line, we start the script via:

php -dxdebug.remote_enable=1 \
    -dxdebug.remote_autostart=On \
    -dxdebug.idekey=$ideKey \
    -dxdebug.remote_port=9000 \
    some-script.php

Where $ideKey by convention is the unix username and port is 9000 or whatever port XDebug was configured to use.

Debug controls:

When to Step Over, Into, or Out

The step over, into, and out of always tricks me up. First, contrary to what I thought, you can’t use step-over to step over loops. They only effect whether you are stepping into, over, and out of function or method calls. Essentially, if a function is to be called on the line under evaluation if you step-into it, then we step into the function and debug line by line that function. If we step-over it, then the debugger executes the function and takes us to the next line in the current context. Step-out is used if we first stepped into a function and now want to simply execute to the end of that function and step back up to the calling context.