Debug Mode

Syntax
$connection->debug = boolean|int;

Description

Enabling debug mode makes the driver return debugging information from both ADOdb and the PHP driver itself.

The output includes the executed SQL statement with parameters, as well as error messages and backtrace information if there are problems. It is suitable for viewing in a browser (see Formatting section below)

See Logging for details on how to capture and redirect output.

Usage

The debug option can be enabled and disabled at any time, to debug portions of a program. The earliest it can be set is after the inclusion of the driver, and before the connection.

In the following example, the table name is spelled incorrectly (it should be products). When run without debugging, the execution of the statement produces no output and simply returns false. 

include 'adodb.inc.php';
$conn = newAdoConnection('mysqli');
 
# Here is the earliest point where Debug Mode can be set

$conn->connect($host, $user, $pass, 'database');
 
# Enable Debug mode
$conn->debug = true;
 
$recordSet = $conn->execute('SELECT * FROM product');

The information returned on STDOUT is: 

------------------------------------------------------------------------------
mysqli: SELECT * FROM product
------------------------------------------------------------------------------
Query: select * from product failed. Table 'database.product' doesn't exist
1146: Table 'database.product' doesn't exist

Call stack (most recent call first):
 2. ADOConnection::_Execute(SELECT * FROM product) in .../drivers/adodb-mysqli.inc.php line 1091
 1. ADODB_mysqli::execute(SELECT * FROM product) in .../test.php line 36

By default, the parameters passed to the query are compressed into a set of key ⇒ value pairs. This information is printed after the SQL statement, using a <code> tag. Styling can be applied using CSS, see Formatting section below.

Possible values

In addition to the standard True and False states accepted by this switch, there are 3 additional non-boolean values that, if set, will vary some of the output produced.

Value Description
False Debug mode disabled (normal operations)
True Standard mode, prints executed SQL statements and error information including a Backtrace if the query failed.
-1 Same as Standard mode, but with the line separators around the SQL statements suppressed.
99 Prints a Backtrace after every query execution, even if the execution is successful.
-99 Debug information is only printed if query execution failed, reducing the amount of output.

Formatting

Starting with ADOdb 5.23.0, debug output is printed with HTML markup and styled with CSS classes. This can be leveraged to improve display of various elements. The output's structure is as follows:

Here is how the output looks like with the basic stylesheet below 

.adodb-debug-sql code {
    font-size: large;
}
.adodb-debug-errmsg {
    font-weight: bold;
    color: red;
}
.adodb-debug-trace table {
    border-spacing: 0;
    border: 1px solid;
}
.adodb-debug-trace thead {
    background-color: darkgray;
}
.adodb-debug-trace th, .adodb-debug-trace td {
    border: 1px solid;
    padding: 2px 6px;
}

Limitations