Sam Tuke Open Source Entrepreneur

The release of PHP 5.6 is imminent, and it’s about to bring a little-known debugging tool into the limelight and package repositories everywhere. Here’s a quick-start guide to making phpdbg useful.

A note on setup
Although phpdbg is part of the official release, it is bundled in a separate package, like many other PHP components. To install both PHP 5.6 and phpdbg immediately, follow my guide for Fedora. The easier route is to simply wait a few days until the release is official, update your system, then install new package ‘php-dbg’.

What we’ll achieve

1. Open the file for debugging with phpdbg
2. Add a strategic breakpoint
3. View all variables set during paused execution
4. Examine a variable’s current value during paused execution
5. Reassign values to a variable during paused execution
6. Complete code execution and examine the impact of changes on script output

Demo code

We’ll use a brief demo class for showing breaking and debugging procedures. Save this class locally by downloading the script file or copy pasting the script below.

<?php

class GreetingClass
{
	public $fromName = 'Anna';
	public function doGreeting( $toName = null )
	{
		print( 'Hello '.$toName.'! From '.$this->fromName );
	}
}
$myName = 'Saskia';
$greeter = new greetingClass();
$greeter->doGreeting( $myName );

?>

Walkthrough

1. First of all execute the class file to check the output, for comparison later:
   php -f /path/to/greetingClass.phpOutput: “Hello Saskia! From Anna”
2. Now start up phpdbg and begin debugging:
   phpdbg -e /path/to/greetingClass.php // leave a space after the -e flag, unlike documentation
3. add a break point just after the $myName variable has been set:
   b 12 // break on line 12
4. execute the loaded PHP script
   runYou should see a message saying the breakpoint has been hit (“Hits: 1”)!
5. Print the class source to terminal, for reference (was the right name Saskia, or Slazenger?):
   l c GreetingClass
6. Check which variables are currently set:
   info vars
7. Check the value of var $myName:
   ev $myName
8. Change the value of $myName, while execution is still paused, to see how it affects the final output:
   ev $myName = 'Yael'
9. Proceed slowly through the next two script script ‘steps’, execute FETCH_CLASS and METHOD_CALL:
   step
step
10. Finish logical execution of the script:
    finish
11. exit and clear the session
    q

Practical uses

The ability to view var values at any point of an executing script is extremely useful. Where is that NULL value being introduced? When are those $_SESSION vars being changed? – hunting down the culprit just became much easier.

Being able to *change* those values is even more important however, especially for large and complex codebases. Seeing what impact a different length string, or longer decimal number has at step 50 of 500 or normal script processing can be extremely time consuming using conventional means, finding how and when the value arries there and how to print it to terminal. Simply adding a break allows unlimited addition and modification of such values however, providing major relief.

Although they’re not covered here, watch points are also settable in phpdbg, and are a very big deal. Check out the official documentation for related commands and examples.