A PHP Script Debugging Method

The PHP script debugging method described here is the one I use more than any other. In fact, it generally gets set it up when I begin development of any significant PHP script.

This article is about finding and fixing bugs that cause the software to operate not quite like expected. The article is not about correcting errors and warnings that PHP tells you about. For those, server error logs are your friends.

The debugging process inserts information into a debugging file. Generally, the information is the value of one or more variables and the relevant line number. (The line number can be especially valuable when the same variable is used with different values at different points in the PHP script.)

The following two PHP lines set it up. Generally, the set up is near the top of the PHP script so it is available throughout.

$DebuggingFile = false;
#$DebuggingFile = "debug_" . time() . "_" . (preg_replace("!^.*/!","",$_SERVER["PHP_SELF"])) . ".txt";

That first line sets the $DebuggingFile variable to false. If not overridden, the false value prevents the debugging process from kicking in.

The second line is disabled in the above example. If the line was live, it would override the value in the previous line by specifying a file name to receive information during the debugging process.

When I need to enable the debugging process, I remove the "#" character from the front of the second line. When done debugging, I replace the "#" character.

During the debugging process, that second line creates a new file name every time the PHP script runs. The file name contains a time() timestamp and also the file name of the PHP script being debugged.

Custom debugging lines at key points within the script insert information into the debugging file. Later in the article, I'll describe the debugging lines you might use.

This particular PHP script debugging method works for me because it is effective and is incredibly quick to implement.

I can start and stop the debugging process without going through the code in the rest of the PHP script to remove unwanted debugging lines — then putting it all back again if a different error turns up that isn't easily detectable.

With any experience creating a significant PHP script from scratch, you undoubtedly have run into bugs that were not easily spotted.

Oh, the bug was spotted. No problem there. It was clear that something was wrong.

But the reason for the bug might be rather elusive.

Sometimes it takes guessing, trying this and that to see what happens, perhaps going line by line through a function, before the reason for the bug is revealed.

That's where this PHP script debugging method earns its keep.

Wherever you are uncertain what specific variables may contain, variables that might be part of the bug, you insert a debugging line.

The Debugging Line

The debugging line inserts information into the debugging file. Here is a template of the debugging line.

if($DebuggingFile) { file_put_contents($DebuggingFile,__LINE__.":\n"."[DEBUGGING_INFORMATION]"."\n\n",FILE_APPEND); }

Only if the $DebuggingFile variable is not false does the debugging line get inserted into the debugging file.

The debugging information starts with the line number (__LINE__), a semi-colon character, and a line feed. This tells you at which script line the debugging information was inserted into the debugging file. Further, it makes it easier to find if you end up with lots of different line numbers in the debugging file.

Your custom debugging information ("[DEBUGGING_INFORMATION]") follows the line information, then two line feeds to insert a blank line between this debugging line's information and any that may follow.

At that point, the entire block of information is appended to the debugging file.

Insert custom debugging lines into your code wherever it might provide information to help you resolve a bug.

Replacing the "[DEBUGGING_INFORMATION]" Placeholder

In the above debugging line template, replace "[DEBUGGING_INFORMATION]" with your debugging information.

Your debugging information might be a simple statement for reference, like "Am now entering function MyFunc()". See this example.

if($DebuggingFile) { file_put_contents($DebuggingFile,__LINE__.":\n"."Am now entering function MyFunc()"."\n\n",FILE_APPEND); }

Or, the debugging information might contain a variable name and the variable's value, as "\$MyVariable=$MyVariable" would do. Here is an example.

if($DebuggingFile) { file_put_contents($DebuggingFile,__LINE__.":\n"."\$MyVariable=$MyVariable"."\n\n",FILE_APPEND); }

The above example is for a scalar variable. (A scalar variable is a variable that holds one value at a time.)

For arrays (variables that can hold more than one value), the print_r() function can be used. "\$MyArray:".print_r($MyArray,true) would insert every value the $MyArray variable contains. See this example.

if($DebuggingFile) { file_put_contents($DebuggingFile,__LINE__.":\n"."\$MyArray:".print_r($MyArray,true)."\n\n",FILE_APPEND); }

The above example debugging lines might insert something like this into the debugging file:

839:
Am now entering function MyFunc()

841:
$MyVariable=Very purple

880:
$MyArray:Array
(
    [one fruit] => Apple
    [another] => Orange peel
)

When the bug is found and corrected, you may disable the second $DebuggingFile line at the setup that specifies a debugging file name.

Why?

The entire point of the debugging lines is to gain information that might provide clues to the reason for a particular bug.

That's it. That's all it's for. I find it very useful when needed and hope you do, too.

By the way, when you are done with development, you can leave the debugging lines in place or remove them. If the software is to be distributed, it probably would be more elegant to remove them. (For my own use, I leave them in. I tend to tweak what I use and the debugging lines can be handy already being in place.)

(This article first appeared with an issue of the Possibilities newsletter.)

Will Bontrager