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 5 hook types, as explained below.

pre_parse

This hook runs before the "parsing" step, where the inputted query is compiled, escaped, and prepared to be run. It receives the query and arguments, and can modify them if it wants. It can optionally return an array of two elements, where the first is the new query and the second is the new args array.

$fn = function($hash) {
    $query = $hash['query'];
    $args = $hash['args'];

    // edit the query before it's run
    $query .= ' AND username=%s';
    $args[] = 'Joe';

    return [$query, $args];
}

// this hook won't change the query, but will just display query and args on the screen
$fn2 = function($hash) {
    $query = $hash['query']
    $args = $hash['args'];

    echo "QUERY: $query\n";
    echo "ARGS: " . implode(', ', $args);
}

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

DB::query("SELECT * FROM accounts WHERE name=%s AND age=%i", 'Joe', 15);
// pre_parse hooks will receive:
// $query: SELECT * FROM accounts WHERE name=%s AND age=%i
// $args: ['Joe', 15]

pre_run

This hook runs after the "parsing" step, but before the query is executed. It will not get separate query and args, since those have now been combined into a single ready-to-run query.

$fn = function($hash) {
    $query = $hash['query'];

    // alter the query before it's run
    $query = strtoupper($query);

    return $query;
}

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

    echo "QUERY: $query\n";
}

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

DB::query("SELECT * FROM accounts WHERE name=%s AND age=%i", 'Joe', 15);
// pre_parse hooks will receive:
// $query: SELECT * FROM accounts WHERE name='Joe' AND age=15

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)
    $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)

    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
    $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..."