Raising An Alarm - PHP

The traditional method of building dynamic, PHP-based Web sites - mixing HTML elements with PHP code - can result in mangled Web pages (and much user angst) if errors take place during script execution. But yes, you can avoid the ugliness - plug in our handy error reporting class, which provides a simple way of trapping script errors and generating consistent, user-friendly error screens.

TABLE OF CONTENTS:

By: icarus, (c) Melonfire

Poor Best

Rating:

/ 21

December 11, 2002

print this article

SEARCH DEV SHED

TOOLS YOU CAN USE

Next, the real meat of this class - the method used to raise errors and add them to the error stack:

<?php
class errorReporter
{
// manually raise an error
function raiseError($subtype=NULL, 
$data="No additional
information
available")
{
$this->_errors[] = array("subtype" 
=> $subtype, "data"
=> $data);
if ($this->_getErrorType($subtype) < 1000)
{
// 
fatal
$this->displayFatalError($subtype, $data);
}
return $this->_errors;
}
// 
snip
}

The raiseError() method is invoked by the developer whenever a need arises to capture an error in a script; it must be sent an error code identifying the error type, together with an optional explanatory message or debug data. The error thus raised is added to the $_errors array, for further processing as and when needed.

In the event that the error raised is a fatal error, the raiseError() class also invokes the displayFatalError() method. The determination of whether or not an error is fatal is handled by the _getErrorType() private method, which merely checks the error code to see if it's above or below 1000.

<?php
class errorReporter
{
// internal function to map subtype to primary 
type
function _getErrorType($subtype)
{
return floor($subtype/10)*10;
}
// 
snip
}

If an error is fatal, the displayFatalError() method is invoked. Here's what it looks like:

<?php
class errorReporter
{
// fatal error handler
// clear previously-drawn 
screen
// display error template with message
// stop script processing and 
die()
function displayFatalError($subtype, $data)
{
ob_clean();
$errorType 
=
$this->_errorTypes[$this->_getErrorType($subtype)];
$errorCode = $subtype;
$errorMsg 
= $this->_errorsubTypes[$subtype];
$addInfo = $data;
include("error-fatal.php");
die;
}
// 
snip
}

This method receives the error code and debug data as input, and has to perform a number of important tasks.

First, it needs to clear the output buffer of all previously generated content, so as to avoid the mangled screen I showed you near the beginning of this article. In order to do this, it uses the ob_clean() function discussed previously.
Next, it needs to display an error template, and insert appropriate content into it reflecting the nature of the error. Using the error code passed to it as argument, this function looks up the $_errorsubTypes array defined at the top of the class, and maps the error code to the corresponding human-readable error message. This data is then inserted into the error template, which contains placeholders for the error type, error message and debug data and takes care of providing the consistent error handling earlier stated as one of the design goals for this class.
Finally, once the error screen has been displayed, it has to terminate further script processing via a call to die().

The error template to be displayed here is contained within a separate file, named "error-fatal.php", and include()-d where needed by displayFatalError(). This template can be customized to your specific requirements - here's my bare-bones version:

<html>
<head>
<basefont face="Arial">
</head>
<body>
<p> 
<p>
<table width="100%" border="0" cellspacing="0" cellpadding="5"
bgcolor="Navy"> 
<tr>
<td bgcolor="Navy" width="100%"><font
color="white"><b>Error!</b></font></td>
</tr>
</table>
<p>
The 
following fatal error occurred:
<p>
<b><?=$errorType?> (error code 
<?=$errorCode?>)</b>
<br>
<?=$errorMsg?> (<?=$addInfo?>)
</body>
</html>

Wanna see how it works? Here's an example of how you could use the errorReporter in a script to trap fatal errors,

<?php
// include class
include_once("errorReporter.class.php");
// initialize 
error reporter
$e = new errorReporter();
echo "Beginning work...";
// write 
to file
$filename = "data.txt";
$fd = fopen ($filename, "wb") or $e->raiseError(208, 
$filename); $ret =
fwrite ($fd, "aloha!") or $e->raiseError(207, $filename); 
fclose 
($fd);
// zero errors?
// display success code
echo "Success!";
?>

and here's an example of the error screen displayed if an error occurs during script execution:

Note the manner in which the output generated by the script above is first cleared from the output buffer by the errorReporter class, and is then completely replaced with the template containing an appropriate error message. No more mangled screens, no more confused users!

Next: A Well-Formed Idea >>