Differences

This shows you the differences between two versions of the page.

--- userguide:error_handling [2015/10/16 20:39] – mnewnham
+++ v5:userguide:error_handling [2018/06/27 16:18] (current) – function names starting with lowercase (#430) dregad
@@ Line 1: / Line 1: @@
 ====== Error Handling  In ADOdb ======
 ===== Default Behaviour =====
-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.
+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.
-===== adodb-errorhandler =====
+===== PHP set_error_handler =====
-*   adodb-error.inc.php and lang/adodb-$lang.inc.php (if you use MetaError())
+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.
-*   adodb-exceptions.inc.php and adodb-errorhandler.inc.php (if you use adodb error handler or php5 exceptions).
-==== Standard Version ====
+---------------------------------------------------
-==== Customization ====
+<WRAP right box round>
-ADOdb supports PHP5 exceptions. Just include _adodb-exceptions.inc.php_ and you can now catch exceptions on errors as they occur.
+== See Also ==
+[[v5:reference:connection:metaerror|Meta Error Handling]]
+</WRAP>
+===== adodb-errorhandler.inc.php =====
+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.
 <code php>
+include 'adodb-directory/adodb.inc.php';
+include 'my-directory/adodb-errorhandler.inc.php';
+$db = newAdoConnection('mysqli');
+$db->connect('','user','password','employees');
 /*
- * Connection to database assumed
+* Invalid SQL statement will be trapped inside the custom errorhandling file
 */
-include("../adodb-exceptions.inc.php");
+$result = $db->execute('SELECX * FROM products');
-try {
-    $db = NewADOConnection("oci8://scott:bad-password@mytns/");
-} catch (exception $e) {
-    var_dump($e);
-    adodb_backtrace($e->gettrace());
-}
 </code>
+===== error_reporting =====
+The ADOdb error handler is not dependent on [[http://php.net/manual/en/function.error-reporting.php|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.
-ADOdb also provides two custom handlers which you can modify for your needs. The first one is in the **adodb-errorhandler.inc.php** file. This makes use of the standard PHP functions [[http://php.net/error_reporting|error_reporting]] to control what error messages types to display, and [[http://php.net/trigger_error|trigger_error]] which invokes the default PHP error handler.
+<code php>
+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
+</code>
-Including the above file will cause _trigger_error($errorstring,E_USER_ERROR)_ to be called when
- (a) Connect() or PConnect() fails, or
-(b) a function that executes SQL statements such as Execute() or SelectLimit() has an error.
- (c) GenID() appears to go into an infinite loop.
-The $errorstring is generated by ADOdb and will contain useful debugging information similar to the error.log data generated below. This file adodb-errorhandler.inc.php should be included before you create any ADOConnection objects.
+===== Override Error Trap/Resume =====
+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.
-If you define error_reporting(0), no errors will be passed to the error handler. If you set error_reporting(E_ALL), all errors will be passed to the error handler. You still need to use **ini_set("display_errors", "0" or "1")** to control the display of errors.
+<code php>
+/**
+  * 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;
+</code>
+===== Using A Class Method =====
 <code php>
-error_reporting(E_ALL); # pass any error messages triggered to error handler
+class c
+{
+	function e()
+	{
+		print "ERROR TRAP";
+	}
+}
-include('adodb-errorhandler.inc.php');
+$c = new c;
-include('adodb.inc.php');
-include('tohtml.inc.php');
-$c = NewADOConnection('mysql');
+$db->raiseErrorFn = array($c,'e');
-$c->PConnect('localhost','root','','northwind');
-$rs=$c->Execute('select * from productsz'); #invalid table productsz');
-if ($rs)
-    rs2html($rs);
 </code>
+===== Combining With Custom Error Handling =====
+If you use ''adodb-errorhandler.inc.php'', you can still define your own error handling to deal with non-adodb errors.
+<code php>
+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';
+</code>
+===== Exception Trapping =====
+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.
+<code php>
+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());
+}
+</code>
+===== Logging Error Messages =====
+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
-If you want to log the error message, you can do so by defining the following optional constants ADODB_ERROR_LOG_TYPE and ADODB_ERROR_LOG_DEST. ADODB_ERROR_LOG_TYPE is the error log message type (see [error_log](http://php.net/error_log) in the PHP manual). In this case we set it to 3, which means log to the file defined by the constant ADODB_ERROR_LOG_DEST.
+ADODB_ERROR_LOG_TYPE is the error log message type (see [[http://php.net/manual/en/function.error-log.php|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.
 <code php>
@@ Line 66: / Line 155: @@
-$c = NewADOConnection('mysql');
+$c = newADOConnection('mysql');
-$c->PConnect('localhost','root','','northwind');
+$c->pConnect('localhost','root','','northwind');
-$rs=$c->Execute('select * from productsz'); ## invalid table productsz
+$rs=$c->execute('select * from productsz'); ## invalid table productsz
 if ($rs)
@@ Line 78: / Line 167: @@
 The following message will be logged in the error.log file:
--10-28 14:20:38 mysql error: [1146: Table 'northwind.productsz' doesn't exist] in  EXECUTE("select * from productsz")
+-10-28 14:20:38 mysql error: [1146: Table 'northwind.productsz' doesn't exist]
+          in  EXECUTE("select * from productsz")
 ===== PEAR_ERROR =====
@@ Line 90: / Line 180: @@
 include('tohtml.inc.php');
-$c = NewADOConnection('mysql');
+$c = newADOConnection('mysql');
-$c->PConnect('localhost','root','','northwind');
+$c->pConnect('localhost','root','','northwind');
-$rs=$c->Execute('select * from productsz'); #invalid table productsz');
+$rs=$c->execute('select * from productsz'); #invalid table productsz');
 if ($rs)
@@ Line 118: / Line 208: @@
 ===== MetaError and MetaErrMsg =====
-If you need error messages that work across multiple databases, then use [[reference:metaerror|MetaError()]], which returns a virtualized error number, based on PEAR DB's error number system, and [[reference:metaerrmsg|MetaErrMsg()]].
+If you need error messages that work across multiple databases, then use [[v5:reference:connection:metaerror|MetaError()]], which returns a virtualized error number, based on PEAR DB's error number system, and [[v5:reference:connection:metaerrormsg|MetaErrMsg()]].
 ===== Error Messages =====
-Error messages are outputted using the static method ADOConnnection::outp($msg,$newline=true). By default, it sends the messages to the client. You can override this to perform error-logging.
+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.