Troubleshooting

ezSQL Troubleshooting Guide

Below are some basic troubleshooting guidelines when using ezSQL.

Click any of the methods in the Table of Contents (ToC) below to be taken to the detailed documentation.

Instructions on how to run a phpunit test can also be found below.

Troubleshooting Methods Table of Contents

$db->debug -- Prints the last sql query and returned results (if any)

$db->debugOn -- turns the debug echo on.

$db->debugOff -- turns the debug echo off.

$db->varDump -- Prints the contents and structure of any variable

$db->hide_errors -- Turns the ezSQL error output to browser off

$db->show_errors -- Turns the ezSQL error output to browser on

Detailed Documentation

debug( void )

Description

Running this method will print a debug result of the last successful sql query and returned results (if any)

Note: Requires $db->debugOn(); or $db->setDebug_Echo_Is_On(true); to print anything out on the page.

Example Use

If you need to know what your last query was and what the returned results are here is how you do it.

<?php
// Set debug on
$db->debugOn();

// Run a query
$users = $db->get_results(“SELECT name, email FROM users”);

// Debug the output/See what just happened!
$db->debug();

---

debugOn( void )

Description

Running this method will enable the $db->debug() method to print out on the page when called. This is the same as and replaces $db->setDebug_Echo_Is_On(true);

Example Use

<?php
// Set debug on
$db->debugOn();

// Run a query
$users = $db->get_results(“SELECT name, email FROM users”);

// Debug the output/See what just happened!
$db->debug();

---

debugOff( void )

Description

Running this method will disable the $db->debug() method from printing out on the page when called.

Example Use

<?php
// Set debug off
$db->debugOff();

// Run a query
$users = $db->get_results(“SELECT name, email FROM users”);

// Nothing will print to the page if you try run this method with debugOff()
$db->debug();

---

varDump( $var )

Description

Running this method will print the contents and structure of any defined variable.

Example Use

If you need to know what value and structure any of your results variables are here is how you do it.

<?php
// Run a query
$users = $db->get_results(“SELECT name, email FROM users”);

// View the contents and structure of $users
$db->varDump($users);

Extra Information

This method is especially useful to trace your last query in conjunction with the $db->debug() method. It will give you a more detailed overview of the defined variable, and the previous queries leading up to it.

It does not matter what the structure of the defined variable is, be it an object, associative array, or numerical array.

---

hide_errors( void )

Note: This method is no longer supported after version 3.0.x. Please use debug() instead.

Description

Running this method will turn the ezSQL error output to the web page off.

Example Use

<?php
// If you are using a custom error function
$db->hide_errors();

// Make a silly query that will produce an error
$db->query(“INSERT INTO my-table A BAD QUERY THAT GENERATES AN ERROR”);

// And another one, for good measure
$db->query(“ANOTHER BAD QUERY THAT GENERATES AN ERROR”);

// If the global error array exists at all then we know there was 1 or more ezSQL errors..
if ( $EZSQL_ERROR ) {
  // View the errors
  $db->varDump($EZSQL_ERROR);
} else {
   echo “No Errors”;
}

Extra Information

This method stops any error output from being printed to the web page. If you would like to stop the error output but still be able to trap errors for debugging or for your own error output function you can make use of the global error array $EZSQL_ERROR.

If there were no errors, then the global error array $EZSQL_ERROR will evaluate to FALSE. If there were one or more errors then it will have the following structure. (Errors are added to the array in order of being called.)

$EZSQL_ERROR = Array (
  [0] => Array ( 
    [query] => SOME BAD QUERY
    [error_str] => You have an error in your SQL syntax near ‘SOME BAD QUERY' at line 1
  )
  [1] => Array (
    [query] => ANOTHER BAD QUERY
    [error_str] => You have an error in your SQL syntax near ‘ANOTHER BAD QUERY' at line 1
  )
  [2] => Array (
    [query] => THIRD BAD QUERY
    [error_str] => You have an error in your SQL syntax near ‘THIRD BAD QUERY' at line 1
  )
)

---

show_errors( void )

Description

Note: This method is no longer supported after version 3.0.x. Please use debug() instead.

Running this method will turn the ezSQL error output to the web page back on.

Example Use

<?php
// If you are not using a custom error function
$db->show_errors();

// Make a silly query that will produce an error. This will output an error to the browser.
$db->query(“INSERT INTO my-table A BAD QUERY THAT GENERATES AN ERROR”);

Extra Information

If you have not used the method $db->hide_errors(); this method ($db->show_errors();) will have no effect.

How to run a PHPUnit test

When reporting an issue you may be asked to run a PHPUnit test. This is a very simple test to run when you know how to run it. Please follow the steps below to run the test.

Note: Detailed instructions on how to setup PHPUnit can be found on the official website at https://phpunit.de/

This method assumes you will be running the test with the composer setup.

1. Download a clean copy of ezSQL at https://github.com/ezSQL/ezsql/releases
2. Extract the files to their own folder in your web folder (e.g. C:\xampp\htdocs if local testing)
3. Open the folder location you extracted the files into in a command line interface (CLI). Make sure the folder selected is the same folder that the lib, tests, and vendor folders are in.
4. Open up you database interface (e.g. PHPMyAdmin)
5. Create a database called ez_test
6. Create a user called ez_test with the password ezTest and give it access and control of the ez_test database you just created.
7. Return to your CLI and run the following commands.

-> composer update
-> vendor/bin/phpunit

If this runs successfully it will generate folder in the same location called build

8. Open the newly generated build\coverage folder in your web browser to read the generated report (e.g. http://localhost/ezsql_master/build/coverage if your folder is in C:\xampp\htdocs\ezsql_master\ if local testing)