Vim As A PHP IDE - Debugging

This blogpost is part of the "Vim As A PHP IDE" series, which starts here.

A few weeks ago, I ended the "Vim As A PHP IDE" series with the refactoring post. However, there's a huge thing missing from this series, and that's debugging. A lot of people debug their code using var_dump and echo, or worse, with self-made methods to markup the things they want to dump. Not only is this very old-school, there are also problems with this method. For instance, the dumped code affects the behaviour or the output of the running script. This is where the step debugger comes in.

A step debugger lets you step trough your code while it's running, so that you can inspect variables on the fly. This eliminates the need for dumping lines to the standard output, while giving you more insight in what's happening. e.g. you can see the whole stack trace and step through that as well...

How does this work?

Basically, the debugger, in the case of PHP xdebug, hooks into the running code and exposes an API that you can use to set breakpoints, make the compiler run, etc... To install xdebug, follow the instructions on their documentation page. Now you'll also have to add some lines to your php.ini configuration file. In my case it looks like this:

[xdebug]
zend_extension="/path/to/xdebug.so"
xdebug.remote_enable=1

The important part is the remote_enable=1, which allows us to hook into the step debugger.

Then you, as a user, sets a breakpoint somewhere and inspects the state of the program at that point, using a "client" that knows how to speak the language of the debugger's API and integrates with your IDE. In our case that client is going to be the Vim plugin Vdebug. You can install the plugin using your favorite plugin installation method.

Debugging our first script

Let's create a script test.php that we want to debug:

<?php

$foo = 'bar';
$foo = 'baz';

We want to see what's inside the $foo variable during the time this script runs. In Vim, press F5 to activate Vdebug. Now, run the script with debugging enabled:

XDEBUG_CONFIG="idekey=xdebug" php test.php

You'll notice that the script seems to hang. In Vim, however, you'll see something like this happening:

That's right! A new tab opened in Vim, containing the Vdebug window with the first breakpoint active. You can instantly see the local variables on the right, as well as the stack trace. If we now move our cursor to line 4 and press F9, to make the debugger run to that line and inspect the state right before it, we'll see that the $foo variable's value was changed to 'bar'. Look ma, no var_dump!

You can also see the superglobals by hitting that tab in the variables screen:

Great! Now you know the basics. Take a look at the other things you can do while debugging (stepping out, stepping over, etc) with Vdebug on their documentation's Quick Guide section. To quickly stop debugging and return to where you were before, press F6 twice.

Tip: if you don't want to set the environment variable every time, you can make XDebug try and run a remote debugger session all the time, and hook into it when you want to by enabling your client. Put this extra line in your php.ini configuration file:

xdebug.remote_autostart=1

Debugging code that is run by a webserver

Running the debugger for web requests is also possible. If the webserver is running on your local machine, you don't have to change much (assuming XDebug is installed and configured as above): just append a parameter to your URL, like this XDEBUG_SESSION_START=xdebug. For instance, https://foo.local/test.php would become https://foo.local/test.php?XDEBUG_SESSION_START=xdebug. The debugger will now try to connect to your client!

So hereby we conclude this blog series about Vim as an IDE once more, and we hope that you liked it! Happy Debugging!