How to use a PHP debugger in Drupal

Hi, I'm Chris Shattuck with BuildaModule dot com and I'm going to spend a little time talking about PHP debugging. So when you get into development work, you're going to run into errors and there's an evolution that developers go through as they start to find techniques to identify where these errors occur. So the first thing that we end up doing is using the echo statement or print statement in PHP to echo a string on the screen so that we can see what's going on behind the scenes.

But that's really limited because if we're trying to pinpoint an error, there's a lot of information that we're not getting. So we might use this technique to find out if a string has been set, what it's been set to. But what do we do if there's an array or an object or we need more background information.

We end up using this to find out also if functions have been triggered. This is the simplest technique. It's used all the time, but there's a way better way.

If you start to develop a little into PHP and you learned some of the more obscure functions, you'll end up using something like this. So let me work out if this string of function calls here. To get defined_var's function is pretty useful if you use that in a function or this is particular useful in Drupal templates if you don't have a PHP debugger available.

What it will do is grab all of the defined variables in that scope. So if you're in a function, it will just grab all of the variables that have been defined in that function, so variables that have been passed to it, global variables, those types of things. If we step out, we see var_dump(), the var_dump() function.

This is really useful too. What that will do is take any variables that get passed to it and output it in a formatted structure so you can see if something is an array and then it will organize it nicely by key value pairs. It outputs objects for strings or even collections of all of these things.

So that's kind of handy. And the die statement kills the page after that's been printed. So if you look at the source of the page, you can see the entire format of text and you don't get all of the other texts that might get outputted as well to try to sort through.

So this is really cool and if you can't use a debugger or you're in the process of trying to figure out how to set yours up, that's okay. This is probably what you'll end up using. The second function, debug_backtrace() is also really handy.

What that will do, if you use that function, say, in a function call, what it will do is trace back what functions have called that function. So if we've got a theme function, then that function would have been called by a more global theme function that calls the theme functions and that function would have been called by your module where you're calling the theme function from. So you can get a feel for what's happened up to that point which is really hard to do if you're just echoing variables.

You can't see how the variables changed or where the variables got passed through. So that's really handy. But ultimately, you're going to want to set up a PHP debugger with Integrated Development Environment.

So there are several development environments out there that are pretty common in the Drupal world. One is Komodo and that works on PC and the Mac. I don't think there's a Linux version.

There may be, and Eclipse which is an Open Source IDE that's free to use, but people have a hard time setting things up with that one. So Komodo costs some money $200 to $300 depending on what version you're getting, but it's one of the most common ones in the Drupal community. And setting up a PHP debugger with it is not that difficult and you will see as we go along why a PHP debugger is so important.

I went years without having this demonstrated to me. So even if you're like, "Ah, I have a system down already. I don't really need anything else.

" I'll demonstrate what happens when you use a PHP debugger, and once you get your set up, you'll never go back. So why is it so awesome? Like why am I spending the time creating this video and why am I so enthusiastic about it? Well, the first thing is that any other technique requires you to add code into your module in order to follow what's going on. So if you want to echo a print var_dump, you're going to have to add that as a line in the code which means that you're going to have to remove it later.

And sometimes, almost everybody has run into this, sometimes you forget and that items ends up going to a production site and it's rather embarrassing when people start seeing these echoed variables or var_dumps and screwing in with the content. It's pretty ugly and you feel like you lose karma as a developer when you do that. So PHP debugging doesn't require anything.

It uses a metafile to store where your points are that you're going to stop during the debugging session. And so the file isn't changed at all. It's really handy.

Also, you can stop at any point during the code, while the code is being processed and you can continue to stop at different points. So if you want to follow a train of functions, you can stop at one and then hit a play button to go to the next stopping point. So you can actively trace a live cascade of effects through your code.

So that's really handy, something you can't do with the print statement. And finally, there's lots of background information when you're going and looking at where debugging point stops. You can see the stack of functions that have been called.

You can see all the variables that have been defined there. You can even watch variables to see how they change from one breakpoint to another breakpoint. So really cool.

Lots of excellent stuff in there. So getting your PHP debugger set up can take a little bit of finesse and it's different depending on your system. So your Apache install might be in a different place.

But let me just go through the stack of technology I'm using for my PHP debugging so you can identify that as I go through the examples what I'm using and if you wanted to mimic that what you need. So first of all, I'm using the Komodo IDE. Komodo has a free version, Komodo Lite but I'm using the full IDE and that's the only one that supports debugging.

And then I'm using the xDebug Apache plugin. This plugs into Apache directly and allows you to use a debugger in your IDE. So you'll need to install that and restart Apache.

I'm using the Firefox browser mainly because of the xDebug Firefox plugin which allows you to trigger a debugging session from the browser directly which is totally invaluable. That's really awesome. And I'm using MAMP which is an installer for Apache, MySQL, PHP on the Mac.

Really simple and easy to set up. Before I get into the examples, I want to share a few resources with you and most of these have to do with integrating xDebug and with your operating system and your IDE. So the first one is on Drupal dot org dot UK and this has a step-by-step instruction guide on setting up Komodo with xDebug.

It's really nice, very useful. There's a couple other places that I found some short little bits that were handy. One in PixilatedDreams dot com and here's the URL.

And then another one on Debuggable dot com. This article is pretty handy. So the final link here is to the xDebug addon for Firefox which allows you to trigger debugging session from the browser directly.

Okay. Let's get to the examples. In my video on the forms API, we took a look at the user login form.

And so we're going to go ahead and take a look at this one again, but we're going to watch how the process occurs through form creation to form validation and finally the user authentication. We're going to follow that process by using a debugger. So I've installed the xDebug plugin which has a couple of little icons in the lower right-hand corner of my Firefox browser.

What I'm going to do is turn it on by just clicking this X here and now it's colored. I'm just going to refresh the page so I'm going to backslash user because we're watching this particular form. Now, you can see at the bottom of my screen that my Komodo icon is bouncing and again Komodo is my IDE and the page here has stopped processing.

So what's happened is that it's passed the call over to Komodo and it's waiting for me to continue through the debugging session. So let's go ahead and step over to Komodo and see what's happening here. So the page that's open here is user dot module.

It automatically opens up the file that is being used to create the page at that moment in the browser. And what I've done is all of these little red stop sign symbols are a sign for a breakpoint and a breakpoint tells Komodo to when this line is called stop here until we tell you to go o ...

Read the last half of the transcript