Watch

Watch is the Drupal watchdog done OO style.

This project started because of the amount of time I have to waste on the Drupal watchdog. I thought about releasing the module on drupal.org, for all of 0.03 microseconds, but drupal.org is not open to new ideas. I will make the code available here as part of the documentation so you can read about the code before downloading, a fresh change from the drupal.org approach where you have to download the code to read the documentation, which is often only the code.

You install Watch the same as any other Drupal module. There are only three files in a directory named watch. You copy the directory into sites/all/modules/ then switch on Watch in the administration modules page. There are no permissions or configuration to worry about.

Use the class direct

The Watch class can be used direct in your code as shown in the following example. You are responsible for passing the resultant object around.

$w = new watch('example_module');

Code	Result
$w->module_name();	example_module
$w->type();	Example module
$w->message();
serialize($w->variables());	a:0:{}
$w->link();

From a Drupal style function

Watch provides a Drupal style function to return an object from the class. The following example shows a watch objected returned from the watch() function. The watch function keeps a list of the objects by module name. When your module has many chunks of code, you can request the same object from everywhere by supplying the same identifier every time you call watch().

$w = watch('example_module');

Code	Result
$w->module_name();	example_module
$w->type();	Example module
$w->message();
serialize($w->variables());	a:0:{}
$w->link();

The identifier is optional

Watch works without the identifier in the function name or class constructor. The following example shows the result. The object is missing the type value for watchdog. You can add the type later.

$w = watch();

Code	Result
$w->module_name();
$w->type();
$w->message();
serialize($w->variables());	a:0:{}
$w->link();

Watch works without the identifier in the function name or class constructor. The following example shows the result. The object is missing the type value for watchdog. You can add the type later.

$w = watch(); $w->type('A type');

Code	Result
$w->module_name();
$w->type();	A type
$w->message();
serialize($w->variables());	a:0:{}
$w->link();

Use your module name

The best identifier is the module name. The following example has an example module name inserted in the function. The identifier keeps the object unique so you can have a different object per module or per component. The identifier is also beautified for use as the watchdog type field. The watchdog type can be used to select specific messages from the watchdog log and helps you find infrequent messages in a busy log.

module_name, type, and link do not change after this point so I will drop them from the results.

Set variables for use in all messages

The following example sets a country variable for use in all messages. Following the watchdog style, the vale name is prefixed with @.

$w->variable_set('@country', 'Australia');

Code	Result
$w->message();
serialize($w->variables());	a:1:{s:8:"@country";s:9:"Australia";}

Here is an example logging of a message using the country variable.

$w->log('Hello from @country');

Code	Result
$w->message();	Hello from Australia
serialize($w->variables());	a:1:{s:8:"@country";s:9:"Australia";}

Here is an example message using the country variable and a one off name variable.

$w->log('Hello @name from @country', array('@name' => 'Joe'));

Code	Result
$w->message();	Hello Joe from Australia
serialize($w->variables());	a:1:{s:8:"@country";s:9:"Australia";}

log()

log() is the general purpose function for logging messages and it follows the watchdog format, except for dropping the type field because that is already defined in the object construction. Everything supplied to log() is saved in the object for later retrieval. Each time you use log(), it overwrites the previous values and saves the new ones.

error()

error() is a shortcut for reporting errors. error() calls log() with the severity set to WATCHDOG_ERROR. There are equivalents for alert(), critical(), debug(), emergency(), info(), notice(), and warning().

backtrace()

backtrace() is a special variation of debug(). backtrace() produces the standard message then a debug_backtrace() list. For easier reading, the list is in the form of one message per level of the backtrace. At this stage the backtrace does not have any options set because of the many changes in recent versions of debug_backtrace. The options could be set in the class and an administration page could configure the options. The options could be configured into the module if someone wants to reward me for the effort. Gift vouchers from Dan Murphys are a good choice.

Set, get, and delete variables

There are functions to set, get, and delete individual variables.

Coderfied

I try to keep code readable but Drupal.org asks for code downgraded to an ancient Unix format and provide a Coder module to enforce the restrictions. The formally clean readable Watch code is dragged back to the format fashions of the 1980s to fit Coder requirements. Although it does not have big hair, a lycra jumpsuit, or sequin covered platform sole boots, it does have the coding equivalents. Plus Coder demands some changes that are the opposite of the drupal.org specifications. I ignored the obviously wrong warning messages from Coder and followed only those that fit the drupal.org specifications.

Download the code

For Drupal 7: watch.zip watch.tar.gz

Conclusion

This is a good useful module and you may prefer to incorporate the code in your own module to avoid the overhead of installing a million tiny modules. All code presented here can be aquired without the restrictions of the GPL license if you need more freedom.