Hook Functions: Add and Remove Hooks

You can add your own functions to run at several different stages of the query process. Your functions could log information, change a query before it's run, or handle errors. Note that the standard way to handle errors is by catching the MeekroDBException that gets thrown, but hooks could allow for more complicated error handling.

$hook_id = DB::addHook(string $hook_type, callable $fn)

Add a hook.

DB::removeHook(string $hook_type, int $hook_id)

Remove the hook. This expects the hook_id returned by DB::addHook().

DB::removeHooks(string $hook_type)

Remove all hooks of a certain type.

Hook Types

There are 4 hook types, as explained below.

pre_run

This hook runs after we "compile" your query into a PDO query, but before we run it. The hook can modify the query, or the arguments, before it's executed.

// this hook will change the query, adding "LIMIT 1" under certain circumstances
$fn = function($hash) {
    $query = $hash['query'];
    $params = $hash['params'];
    $func_name = $hash['func_name'];

    // if the query is only asking for the first row, make sure it has a LIMIT
    if ($func_name == 'queryFirstRow' || $func_name == 'queryFirstField') {
        if (!substr_count($query, 'LIMIT')) {
            $query .= ' LIMIT 1';
        }
    }
    return [$query, $params];
};

// this hook won't change the query, but will display it
$fn2 = function($hash) {
    $query = $hash['query'];
    $params = $hash['params'];
    $func_name = $hash['func_name'];

    echo "QUERY: $query\n";
    echo "PARAMS: [" . implode(',', $params) . "]\n";
};

DB::addHook('pre_run', $fn);
DB::addHook('pre_run', $fn2);

DB::queryFirstField("SELECT password FROM accounts WHERE id=%i", 1);
// $fn2 will output:
// QUERY: SELECT password FROM accounts WHERE id=? LIMIT 1
// PARAMS: [1]

post_run

This hook runs after the query is executed, whether it was successful or not. If there was an error, you can examine the error and exception before it's thrown.

$fn = function($hash) {
    $query = $hash['query'];
    $runtime = $hash['runtime']; // runtime in ms
    $rows = $hash['rows']; // number of rows returned (does not apply for queryWalk())
    $affected = $hash['affected']; // affected rows (for insert/update/delete)
    $func_name = $hash['func_name'];
    $error = $hash['error']; // error message, if any
    $Exception = $hash['exception']; // if error, this exception will be thrown after the hooks run

    echo "QUERY: $query ($runtime ms)\n";
    echo "ERROR: $error\n";
}

DB::addHook('post_run', $fn);

// this broken query will cause the $error and $Exception to be set in the hook
DB::query("SELCT * FROM accounts");

// this successful query will have $error and $Exception as null, but $rows will be set
DB::query("SELECT * FROM accounts");

run_success

Just like post_run, except it only runs if the query was successful.

$fn = function($hash) {
    $query = $hash['query'];
    $runtime = $hash['runtime']; // runtime in ms
    $rows = $hash['rows']; // number of rows returned (does not apply for queryWalk())
    $affected = $hash['affected']; // affected rows (for insert/update/delete)
    $func_name = $hash['func_name'];

    echo "QUERY: $query ($runtime ms)\n";
    echo "ROWS RETURNED: $rows\n";
    echo "AFFECTED ROWS: $affected\n";
}

DB::addHook('run_success', $fn);
DB::query("SELECT * FROM accounts");

run_failed

Just like post_run, except it only runs if the query failed. An exception will be thrown after this hook runs. If this hook returns false, the exception will not be thrown.

$fn = function($hash) {
    $query = $hash['query'];
    $runtime = $hash['runtime']; // runtime in ms
    $func_name = $hash['func_name'];
    $error = $hash['error']; // error message
    $Exception = $hash['exception']; // this exception will be thrown after hooks run

    echo "QUERY: $query ($runtime ms)\n";
    echo "ERROR: $error\n";
}

DB::addHook('run_failed', $fn);
DB::query("SELCT * FROM accounts");
// run_failed hook will receive:
// $error: "You have an error in your SQL syntax..."