Error Handling In ADOdb

By default, errors in the execution of SQL statements are handled by the database driver that is being accessed by PHP. No errors are normally handled and it is necessary to query the last error code to see if there has been an error. This is done by use of the '@' PHP value, that causes errors in the statement to be ignored.

Once the PHP set_error_handler is used to override the default error handling, then the '@' PHP value ceases to be honored, and any SQL statement execution that fails will then produce a fatal error in the statement. We must then implement an error handling layer to trap the error and process it as the required. The first way to do that is by the use of the adodb-errorhandler.inc file.

This file is designed to be copied off and customized for your own use. In it's simplest form, it can be used to emulate the '@' continue-on-error character, but it can be used to trigger or log errors, or do any kind of error handling processing required.

include 'adodb-directory/adodb.inc.php';
include 'my-directory/adodb-errorhandler.inc.php';
 
$db = newAdoConnection('mysqli');
$db->connect('','user','password','employees');
 
/*
* Invalid SQL statement will be trapped inside the custom errorhandling file
*/
$result = $db->execute('SELECX * FROM products');

The ADOdb error handler is not dependent on PHP Error Reporting being set to a value greater than zero. However, the default behaviour of adodb-errorhandler.inc.php is to respect this setting by returning immediately from the error trap. You can change this by modifying the source of that file.

function ADODB_Error_Handler($dbms, $fn, $errno, $errmsg, $p1, $p2, &$thisConnection)
{
 
    /*
    * Remark out this line to trap errors when error_reporting = 0
    */
    if (error_reporting() == 0) 
          return; // obey @ protocol
 

In certain circumstances, it may be necessary to trap errors differently or override the normal error handling. The current error handler, which is stored in the class variable raiseErrorFn, can be temporarily replaced. In this example, we use that functionality to ignore a database error.

/**
  * Traps errors and ignores them
  */
function ignoreErrorHandler()
{
	return true;
}
 
/*
* In Oracle we have no 'if index exists' function, 
* so if the index did not exist in the first place, it would throw an error
* We want the error ignored, and for the program to continue as normal
*/
 
$saveErrorFn = $db->raiseErrorFn;
$db->raiseErrorFn = 'ignoreErrorHandler';
set_error_handler('ignoreErrorHandler');
 
$db->execute('DROP INDEX index_that_might_not_exist');
 
/*
* Set the error handling back
*/	
restore_error_handler();
$db->raiseErrorFn = $saveErrorFn;

class c
{
	function e()
	{
		print "ERROR TRAP";
	}
}
 
$c = new c;
 
$db->raiseErrorFn = array($c,'e');

If you use adodb-errorhandler.inc.php, you can still define your own error handling to deal with non-adodb errors.

error_reporting(E_ALL);
 
function myErrorHandler($p1,$p2,$p3,$p4,$p5)
{
    /*
    * Do some non-adodb handling
    */
    return true;
}
 
set_error_handler('myErrorHandler');
 
include './simple-errorhandler.inc.php';
include '../adodb-master/adodb.inc.php';

ADOdb supports exception trapping using the adodb-exceptions.inc.php file. This can be used to catch exceptions on errors as they occur. In the following example, we trap an invalid user name/password combination as an exception.

include 'adodb-directory/adodb.inc.php';
include 'adodb-directory/adodb-exceptions.inc.php';
 
try 
{   
    $db = newADOConnection("oci8://scott:bad-password@mytns/");   
 
} 
catch (exception $e)
{   
    var_dump($e);   
    adodb_backtrace($e->gettrace());  
}

If you want to log the error message, you can do so by defining the following optional constants:

• ADODB_ERROR_LOG_TYPE
• ADODB_ERROR_LOG_DEST

ADODB_ERROR_LOG_TYPE is the error log message type (see error_log. In the example below, the value is set to 3, which means log to the file defined by the constant ADODB_ERROR_LOG_DEST.

error_reporting(E_ALL); # report all errors  
ini_set("display_errors", "0"); # but do not echo the errors  

define('ADODB_ERROR_LOG_TYPE',3);  
define('ADODB_ERROR_LOG_DEST','C:/errors.log');  
 
include('adodb-errorhandler.inc.php');
include('adodb.inc.php');
include('tohtml.inc.php');
 
 
$c = newADOConnection('mysql');
$c->pConnect('localhost','root','','northwind');
 
$rs=$c->execute('select * from productsz'); ## invalid table productsz

if ($rs) 
    rs2html($rs);

The following message will be logged in the error.log file:

2001-10-28 14:20:38 mysql error: [1146: Table 'northwind.productsz' doesn't exist]
        in  EXECUTE("select * from productsz")

The second error handler is adodb-errorpear.inc.php. This will create a PEAR_Error derived object whenever an error occurs. The last PEAR_Error object created can be retrieved using ADODB_Pear_Error().

include('adodb-errorpear.inc.php');
 
include('adodb.inc.php');
include('tohtml.inc.php');
 
$c = newADOConnection('mysql');
$c->pConnect('localhost','root','','northwind');
 
$rs=$c->execute('select * from productsz'); #invalid table productsz');

if ($rs) 
  rs2html($rs);
 
else 
{
    $e = ADODB_Pear_Error();  
    echo '<p>',$e->message,'</p>';**
}

You can use a PEAR_Error derived class by defining the constant ADODB_PEAR_ERROR_CLASS before the adodb-errorpear.inc.php file is included. For easy debugging, you can set the default error handler in the beginning of the PHP script to PEAR_ERROR_DIE, which will cause an error message to be printed, then halt script execution:

include('PEAR.php');  
 
PEAR::setErrorHandling('PEAR_ERROR_DIE');

Note that we do not explicitly return a PEAR_Error object to you when an error occurs. We return false instead. You have to call ADODB_Pear_Error() to get the last error or use the PEAR_ERROR_DIE technique.

If you need error messages that work across multiple databases, then use MetaError(), which returns a virtualized error number, based on PEAR DB's error number system, and MetaErrMsg().

Error messages are outputted using the static method

ADOConnnection::outp($msg,$newline=true). 

By default, it sends the messages to the standard output. You can override this to perform error logging.