Overview

eac_error.class is a PHP static utility class for error handling. It is intended to be used throughout the PHP application for capture and reporting of errors and exceptions.

The error handling routine in eac_error.class is designed to provide detailed state information for the developer or administrator while still maintaining a secure environment. Error messages are only presented to the web user on true error conditions and do not include information that may be used to compromise the system. Notifications are sent to the webmaster/administrator in an encrypted state (using GnuPG) so that critical, private information cannot be intercepted in transit.

You should have a basic understanding of PHP error and exception handling as well as the ability to create and load keys using GNU Privacy Guard.

See the PHP documentation for error and exception handling:
http://www.php.net/manual/en/ref.errorfunc.php
http://www.php.net/manual/en/language.exceptions.php
and the GNU Privacy Guard web site at http://gnupg.org/.

This class may be used without GnuPG, but one of the major features is the ability to encrypt messages.

Features

• GnuPG encrypted email sent to the web administrator.
• Detailed system information included with email.
• Function and class trace back information included.
• Log errors to a single file or multiple files based on severity (fatal, error, warning ,notice).
• Send email notice for each error or for all errors at the end of script execution.
• Suppress or allow options (email, display, logging, etc.) when error is triggered.
• Provide a program-designated error code with the error message.
• Set a callback function to display errors and abort processing.
• Include user-defined data in the error notification email.
• Error condition detectable by AJAX and CURL.

Usage Summary

eac_error.class.php can be installed in any folder in the server’s PHP include path.

GnuPG should be installed and configured on the web server and a signing key should be created using the email address that will be used by eac_error.class to send email messages. Additionally, the public key for the email address that messages are sent to must be loaded via GnuPG.

If a signing key is not used, messages may still be encrypted but not signed.
If there is no public key for the destination email address, the message cannot be encrypted.

See the GNU Privacy Guard web site at http://gnupg.org/ for more information:

Error Class Instantiation

The error class in eac_error.class is intended to be used statically. There is no need to use the new class instantiation. The public methods in eac_error.class are called using the class name prefix Error:: such as Error::set_error_handler() or Error::trigger().

There are a number of options and configuration constants that may be defined to customize the class.

Constants

The following constants may be defined prior to loading the eac_error.class.php program using the “define(‘constant’,’value’)” PHP function.

Before defining any ERR_TYPE_IS_* constants, make sure that the E_UNCAUGHT_EXCEPTION
constant is defined. This constant is not a standard PHP E_* error constant but is used in the eac_error.class.php program for exception handling.

if (!defined('E_UNCAUGHT_EXCEPTION')) define('E_UNCAUGHT_EXCEPTION', 32768); 

ERR_EMAIL_ADDRESS
The email address that error notifications are sent to. If not define prior to loading eac_error.class.php, the program defines this constant in one of three ways:

1. Using the $_SERVER["SERVER_ADMIN"] variable if it is set.
2. Using the $CompanyEmail global variable if it is set.
3. Using webmaster@$_SERVER['HTTP_HOST'].

ERR_FROM_ADDRESS
The email address that error notifications are sent from. If not define prior to loading eac_error.class.php, the program defines this as the same address as ERR_EMAIL_ADDRESS.

ERR_EMAIL_EOL
Defines the end-of-line character(s) used when the email is generated. The default value is “\n” (line-feed) but some systems may require “\r\n” (carriage-return, line-feed).

ERR_TYPE_IS_ERROR
Defines which error types are to be considered true errors. The default value is:
(E_ERROR | E_PARSE | E_CORE_ERROR | E_COMPILE_ERROR | E_USER_ERROR | E_RECOVERABLE_ERROR | E_UNCAUGHT_EXCEPTION)

ERR_TYPE_IS_WARNING
Defines which error types are to be considered warnings. The default value is:
(E_WARNING | E_CORE_WARNING | E_COMPILE_WARNING | E_USER_WARNING).

ERR_TYPE_IS_NOTICE
Defines which error types are to be considered notices. The default value is:
(E_NOTICE | E_USER_NOTICE | E_STRICT).

ERR_TYPE_IS_FATAL
Defines which error types are to be considered fatal errors. The default value is:
all ERR_TYPE_IS_ERROR error types except E_RECOVERABLE_ERROR, and E_CORE_WARNING | E_COMPILE_WARNING.

ERR_TYPE_IS_DISPLAY
Defines which error types should be displayed to the user. The default value is:
(ERR_TYPE_IS_FATAL | ERR_TYPE_IS_ERROR).

ERR_TYPE_IS_PRIORITY
Defines which error types should set the email priority to ‘high’. The default value is:
ERR_TYPE_IS_FATAL | ERR_TYPE_IS_ERROR | ERR_TYPE_IS_WARNING but not E_USER_WARNING.

Options

Options can be passed in an array to the set_error_handler() and/or setOptions() function or individually to the setOption() function.

Option name	Value	Purpose
detail	true/false	Include system detail in email notification (false for notices).
display	true/false	Display error & fatal message to user.
email	true/false	Send email notification.
history	true/false	Send only one email with all errors at the end of script execution.
logging	true/false	Log errors to file.
debug	true/false	Set debugging (include file name and line number).
html	true/false	Use html in email.
callback	function/false	Use a callback function for error display and abort.
EncryptionRequired	true	Require encryption when including system detail in email.
		! Setting this option to false may be a security risk.
* Default values shown in bold.

 

Configuration Example

// error notification to & from email addresses
define('ERR_EMAIL_ADDRESS','Webmaster@EarthAsylum.com');
define('ERR_FROM_ADDRESS','Postmaster@EarthAsylum.com');
// include the error class
require_once('eac_error.class.php');
// set the GnuPG variables to encrypt the notification email.
Error::setGnuPG($keyid, $passphrase, $path_to_gnupg, $gnupg_home);
// setup our error settings
ini_set('ignore_repeated_errors',1);    // prevent repeated errors
ini_set('html_errors',0);               // no links to PHP manual in errors
// error logging path (defaults to apache or event log)
// %s in error_log is replaced with severity, creating multiple log files.
ini_set('error_log',$_SERVER['DOCUMENT_ROOT'].'/php_error_'.date('Ym').'_%s.log');
// define what error types get reported
error_reporting(E_ALL & ~(E_NOTICE | E_STRICT));
// set the error handler
Error::set_error_handler();
// only display errors when debugging
ini_set('display_errors',Error::isDebug());