ezSQL/ezsql

<?php

namespace ezsql;

/**
 * @method void setDebugAll($args);
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method void setTrace($args);
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method void setDebugCalled($args);
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method void setVarDumpCalled($args);
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method void setShowErrors($args);
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method void setNumQueries($args);
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method void setConnQueries($args);
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method void setCapturedErrors($args);
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method void setCacheDir($args);
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method void setUseDiskCache($args);
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method void setCacheTimeout($args);
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method void setCacheQueries($args);
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method void setCacheInserts($args);
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method void setNumRows($args);
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method void setDbConnectTime($args);
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method void setSqlLogFile($args);
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method void setProfileTimes($args);
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method void setInsertId($args);
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method void setLastQuery($args);
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method void setLastError($args);
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method void setColInfo($args);
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method void setTimers($args);
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method void setTotalQueryTime($args);
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method void setTraceLog($args);
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method void setUseTraceLog($args);
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method void setDoProfile($args);
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method void setLastResult($args);
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method void setFromDiskCache($args);
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method void setDebugEchoIsOn($args);
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method void setFuncCall($args);
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method void setAllFuncCalls($args);
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method void setTable($name);
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method void setPrefix($append);
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 *
 * @method string getDebugAll();
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method string getTrace();
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method string getDebugCalled();
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method string getVarDumpCalled();
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method string getShowErrors();
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method string getNumQueries();
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method string getConnQueries();
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method string getCapturedErrors();
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method string getCacheDir();
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method string getUseDiskCache();
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method string getCacheTimeout();
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method string getCacheQueries();
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method string getCacheInserts();
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method string getNumRows();
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method string getDbConnectTime();
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method string getSqlLogFile();
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method string getProfileTimes();
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method string getInsertId();
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method string getLastQuery();
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method string getLastError();
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method string getColInfo();
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method string getTimers();
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method string getTotalQueryTime();
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method string getTraceLog();
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method string getUseTraceLog();
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method string getDoProfile();
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method string getLastResult();
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method string getFromDiskCache();
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method string getDebugEchoIsOn();
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method string getFuncCall();
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method string getAllFuncCalls();
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method string getTable();
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 * @method string getPrefix();
 * A `ezsqlModel` class property that can be accessed with either
 * a `set` or `get` prefix as a function.
 */
interface ezsqlModelInterface
{
    /**
     * Get host and port from an "host:port" notation.
     *
     * @param string $host
     * @param bool $default
     * @return array of host and port. If port is omitted, returns $default
     */
    public function get_host_port(string $host, bool $default = false);

    /**
     * Store Query/SQL/DB error - over-ridden by specific DB class
     *
     * @param string $err_str
     * @param bool $displayError
     * @return bool
     * @throws Exception
     */
    public function register_error(string $err_str, bool $displayError = true);

    /**
     * Turn error output to browser on.
     *
     * - If you have not used the function `$db->hide_errors()` this function (show_errors)
     * will have no effect.
     */
    public function show_errors();

    /**
     * Turn error output to browser off.
     *
     * Stops error output from being printed to the web client.
     * - If you would like to stop 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 $captured_errors. access by calling `$db->getCaptured_Errors()`
     */
    public function hide_errors();

    /**
     * Kill cached query results
     */
    public function flush();

    /**
     * Log how the query function was called
     *
     * @param string $query
     */
    public function log_query(string $query);

    /**
     * Get one variable, from one row, from the database (or previously cached results).
     *
     * This function is very useful for evaluating query results within logic statements such as if or switch.
     * - If the query generates more than one row the first row will always be used by default.
     * - If the query generates more than one column the leftmost column will always be used by default.
     * - Even so, the full results set will be available within the
     *     array `$db->last_results` should you wish to use them.
     *
     * @param string $query
     * @param int $x - column offset
     * @param int $y - row offset
     * @return bool|mixed
     */
    public function get_var(string $query = null, int $x = 0, int $y = 0, bool $use_prepare = false);

    /**
     * Get one row from the database (or previously cached results)
     *
     * - If the query returns more than one row and no row offset is
     * supplied the first row within the results set will be returned by
     * default.
     * - Even so, the full results will be cached should you wish
     * to use them with another ezSQL query.
     *
     * @param string $query
     * @param OBJECT|ARRAY_A|ARRAY_N $output
     * @param int $y - row offset
     * @return bool|mixed
     */
    public function get_row(string $query = null, $output = \OBJECT, int $y = 0, bool $use_prepare = false);

    /**
     * Get one column from query (or previously cached results) based on column offset
     *
     * Extracts one column as one dimensional array based on a column
     * offset.
     * - If no offset is supplied the offset will default to column 0. I.E the first column.
     * - If a null query is supplied the previous query results are used.
     *
     * @param string $query
     * @param int $x - column offset
     * @param bool $use_prepare - has prepare statements been activated
     * @return bool|mixed
     */
    public function get_col(string $query = null, int $x = 0, bool $use_prepare = false);

    /**
     * Get multiple row result set from the database
     * (or previously cached results), based on query and returns them as
     * a multi dimensional array.
     *
     * Each element of the array contains one row of results and can be
     * specified to be either an object, associative array or numerical
     * array.
     * - If no results are found then the function returns `false`,
     * enabling you to use the function within logic statements such as if.
     *
     * - if setup/active, `prepareActive()` has been called, use
     * prepare statements in SQL transactions.
     *
     * **OBJECT** - `Returning results as an object` is the quickest way to get and
     * display results. It is also useful that you are able to put
     * `$object->var` syntax directly inside print statements without
     * having to worry about causing php parsing errors.
     *
     * **ARRAY_A** - `Returning results as an associative array` is useful if you would
     * like dynamic access to column names.
     *
     * **ARRAY_N** - `Returning results as a numerical array` is useful if you are using
     * completely dynamic queries with varying column names but still need
     * a way to get a handle on the results.
     *
     * **JSON** - `Returning results as JSON encoded` is useful for any interactive dynamic queries.

     * @param string $query
     * @param constant $output Either: `OBJECT`|`ARRAY_A`|`ARRAY_N`|`JSON`
     * @param bool $use_prepare - has prepare statements been activated
     * @return bool|object|array - results as objects (default)
     */
    public function get_results(string $query = null, $output = \OBJECT, bool $use_prepare = false);

    /**
     * Get information about one or all columns such as column name or type.
     *
     * Returns meta information about one or all columns such as column name or type.
     * - If no information type is supplied then the default information type of name is used.
     * - If no column offset is supplied then a one dimensional array is returned with the
     * information type for all columns.
     * - For access to the full meta information for all columns you can use the cached
     * variable `$db->colInfo`, access by calling `$db->getCol_Info()`
     *
     * Available Info-Types:
     * mySQL
     * - name - column name
     * - table - name of the table the column belongs to
     * - max_length - maximum length of the column
     * - not_null - 1 if the column cannot be NULL
     * - primary_key - 1 if the column is a primary key
     * - unique_key - 1 if the column is a unique key
     * - multiple_key - 1 if the column is a non-unique key
     * - numeric - 1 if the column is numeric
     * - blob - 1 if the column is a BLOB
     * - type - the type of the column
     * - unsigned - 1 if the column is unsigned
     * - zerofill - 1 if the column is zero-filled
     *
     * MS-SQL / Oracle / PostgresSQL
     * - name - column name
     * - type - the type of the column
     * - length - size of column
     *
     * SQLite
     * - name - column name
     *
     * @param string $info_type
     * @param int $col_offset
     * @return mixed
     */
    public function get_col_info(string $info_type = "name", int $col_offset = -1);

    /**
     * create cache directory if doesn't exists
     *
     * @param string $path
     */
    public function create_cache(string $path = null);

    /**
     * Store cache
     *
     * @param string $query
     * @param bool $is_insert
     */
    public function store_cache(string $query, bool $is_insert);

    /**
     * Get stored cache
     *
     * @param string $query
     * @return mixed
     */
    public function get_cache(string $query);

    /**
     * Dumps the contents of any input variable to screen in a nicely
     * formatted and easy to understand way.
     *
     * @param mixed $mixed- any type Object, public or Array
     * @return string|void
     */
    public function varDump($mixed = null);

    /**
     * @internal alias for varDump()
     */
    public function dump_var($mixed = null);

    /**
     * Displays the last sql query and returned results (if any)
     *
     * @param boolean $print_to_screen
     * @return string
     */
    public function debug($print_to_screen = true);

    /**
     * Timer related functions
     */
    public function timer_get_cur();
    public function timer_start($timer_name);
    public function timer_elapsed($timer_name);
    public function timer_update_global($timer_name);

    /**
     * Function for operating query count
     *
     * @param bool $all Set to false for function to return queries only during this connection
     * @param bool $increase Set to true to increase query count (internal usage)
     * @return int Returns query count base on $all
     */
    public function count($all = true, $increase = false);

    /**
     * Returns `true` if the database connection is established.
     *
     * @return bool
     */
    public function isConnected();

    /**
     * Returns the `number` of affected rows of a query.
     *
     * @return int
     */
    public function affectedRows();

    /**
     * Returns the last query `result`.
     *
     * @return object
     */
    public function queryResult();

    /**
     * Setup table `name` and `prefix` for global usage on calls to database **method/function** *names* ending with `ing`.
     *
     * @param string $name
     * @param string $prefix
     * @return void
     */
    public function tableSetup(string $name = '', string $prefix = '');
}