PHP Development Annotation

This development annotation process began with a need to know the values of one or several variables while PHP scripts ran — during development of the scripts.

For some PHP scripts, echoing the values on the screen (a debugging system I sometimes use) would not work. Examples are:

• When the script runs independently on the server, there is no screen.

• A PHP script launched with Ajax, where the Ajax is unlikely to welcome unexpected content.

• When a PHP script must send only JavaScript to the browser. Although for some, it may be possible to wrap the values into JavaScript code.

One thing I tried was having scripts send me an email with the values. That worked. But it was awkward because I had to get my email with each script run.

A better method I found for myself was creating a file and appending the values I was interested in. The file could remain open in my text editor for automatic update as its content changes.

It is a method customizable for pretty much every PHP script I work on.

As I used the system, it got various tweaks.

A major one was letting the PHP script itself create a new file with each run of the script. The file's name contains the script's file name and the time it was created.

Another tweak was adding the script source code line number whenever a value is appended to the annotation file. It helps me find things quicker when much is appended to the annotation file.

The system works a treat.

In addition to values of variables, it can be used to annotate script flow, loop counts, and other information that may assist software development.

The System

When the script runs, an annotation file location may be assigned automatically. The idea is for every annotation file location to be different, so the notes for each script run is separate from all the others.

This is the way I do it (along with an easy way to turn system off and on):

$debugFile = false;
$debugFile = __DIR__ . '/' . time() . '_' . mt_rand(1000,9999) . '_' . (preg_replace('!^.*/!','',$_SERVER['PHP_SELF'])) . '.txt';

The first line assigns a value false to the $debugFile variable. It is there so when the second line is commented out no annotation file is created.

The second line assigns a file location to the $debugFile variable.

When you don't want to annotate, comment out that second line by inserting a "#" character at the beginning of the line. That turns the system off. To turn it back on, remove the "#" character.

Here is a list of variable values and functions that go into the construction of the file location.

• __DIR__ is the server directory, the directory of the PHP script that is running.

• time() provides the current 10-digit Unix timestamp.

• mt_rand(1000,9999) provides a 4-digit random number.

• The preg_replace(...) function results in the php script's file name.

Here is an example of a file location constructed with the above code.

/home/username/public_html/1595172375_6851_myProject.php.txt

When the file location has been assigned (not commented out), annotation can proceed.

Each annotation is a line of PHP code. Here is the format.

if($debugFile) { file_put_contents($debugFile,__LINE__ . ":\n" . _________ . "\n\n",FILE_APPEND); }

Replace _________ with the information to be added to the annotation file.

I generally put the a date-time stamp at the beginning of the annotation file. For that, _________ is replaced with the date('r') function.

if($debugFile) { file_put_contents($debugFile,__LINE__ . ":\n" . date('r') . "\n\n",FILE_APPEND); }

_________ can be replaced with any text you want annotated. Here are several examples.

if($debugFile) { file_put_contents($debugFile,__LINE__ . ":\n" . "Variable \$color = $color" . "\n\n",FILE_APPEND); }

if($debugFile) { file_put_contents($debugFile,__LINE__ . ":\n" . "Array \$list is ".print_r($list,true) . "\n\n",FILE_APPEND); }

if($debugFile) { file_put_contents($debugFile,__LINE__ . ":\n" . "Loop number is $i" . "\n\n",FILE_APPEND); }

After the script runs, open the annotation file for the information it contains.

A potential shortcut —

Do you develop on one server (or domain) and use it live on another?

If "yes", the file location can be assigned on the development server and not on the deployment server.

Then you won't need to remember to comment out the file location assignment line before deploying the script.

I develop on my Mac and either localhost or 127.0.0.1 is my server name (depending on the URL used to access the PHP script). For myself, the conditional assignment looks like this.

$debugFile = false;
if( preg_match('/localhost|127\.0\.0\.1/',$_SERVER['SERVER_NAME']) )
{
   $debugFile = __DIR__ . '/' . time() . '_' . mt_rand(1000,9999) . '_' . (preg_replace('!^.*/!','',$_SERVER['PHP_SELF'])) . '.txt';
}

Only if the server name is localhost or 127.0.0.1 is the file location assigned to the $debugFile value. Only then will the annotation file be created and appended to.

To implement that idea, find something unique about your development environment to test. It might be server IP address, the development domain name, the server name, or other unique value. For the above code that I use, the server name is tested.

A productivity boost —

Letting the script create an annotation file during development and maintenance can save a lot of time.

When you're curious about a value, check the annotation file.

With ongoing annotation code present, you may end up with lots of annotation files you never open. Still, it takes much less time to select a group of annotation files and delete them than it does to chase a bug when you are uncertain of a value.

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

Will Bontrager