PHP Interface: Control mysql.general_log access

<?php //  P:\developer\xampp\htdocs\testmysql\Q32451215\MysqlGeneralLogging.php

/**
 * IMysqlGeneralLogging
 *
 * Control the MySQL General Logging Facilities.
 *
 * 1) Control whether to log trace information to the `mysql.general_log` table
 * 2) Control whether to log trace information to a `trace file`
 *
 * Once tracing has started then ALL activity on ANY connection will be logged!
 *
 * Trace file:
 *
 * o When you create the instance you need to supply a directory to store the trace files in.
 *
 * o The default trace file name has the following format:
 *     mysql-log-trace-pdo- <YYYYMMDD-HHMM-SS-nnnnnn> ['-', <User supplied text>] '.txt';
 *     Note: `nnnnnn` is microtime to make the trace files unique.
 *
 *     You can provide your own trace file if you wish (see setLogFile($fullPath).
 *
 * o Creating an instance:
 *    1) MysqlGeneralLogging::newInstanceFromPDO(\PDO $pdoConnection,
                                                  $logFileDirectory);
 *
 *       where: The connection must have the privilege to set `Global Variable`.
 *
 *              The connection is only used to control logging do not use it
 *              for anything else.
 *
 *              The `logFileDirectory` is where the trace files will be generated.
 *
 *     2) MysqlGeneralLogging::newInstanceFromParams($host, $username, $password, $dbname,
 *                                                  $logFileDirectory);
 *
 *       where: The params are the normal details to create a PDO connection.
 *
 * Tracing:
 *   The easiest way is to trace to the table `mysql`.`general_log`...
 *
 *   1) Create connection:
 *      $logging = MysqlGeneralLogging::newInstanceFromPDO(\PDO $pdoConnection,
 *                                                         $logFileDirectory);
 *
 *   2) $logging->startLoggingToTable(); // this will truncate the table by default
 *
 *   3) Run queries with  a separate connection.
 *
 *   4) $logging->stopLogging();
 *
 *   5) $traceContents = $logging->extractLogTable(); // trace table to PHP array.
 *
 *  // ---------------------------------------------------
 *
 *   Using a Trace file...
 *
 *   1) Create connection:
 *      $logging = MysqlGeneralLogging::newInstanceFromPDO(\PDO $pdoConnection,
 *                                                         $logFileDirectory);
 *
 *   2) Create a new Trace file:
 *      $logFile = $logging->newTraceFilename();
 *
 *   3) set the new log file
 *       $logging->setLogFile($logFile);
 *
 *       Note: use $logging->logFile() to get the current log file name
 *
 *
 *   4) $logging->startLoggingToFile(); // this will truncate the file by default
 *
 *   5) Run queries with a separate connection.
 *
 *   6) $logging->stopLogging();
 *
 *   7) Examine the Trace file
 *
 *  // ---------------------------------------------------
 *
 * Documentation Links:
 *
 *  5.1.4 Server System Variables - https://dev.mysql.com/doc/refman/5.5/en/server-system-variables.html
 *
 *  5.2 MySQL Server Logs         - https://dev.mysql.com/doc/refman/5.5/en/server-logs.html
 *
 *  5.2.3 The General Query Log   - https://dev.mysql.com/doc/refman/5.5/en/query-log.html
 *
 *  Useful Stackoverflow Questions and Answers:
 *
 *  How to show the last queries executed on MySQL? -  http://stackoverflow.com/a/678310/3184785
 *
 *
 * @author rfv
 */

interface IMysqlGeneralLogging {

    /**
     * Create an instance from an existing PDO connection.
     * Need privilege to: set global variables`
     *
     * @param \PDO $pdoConnection
     * @param type $logFileDirectory
     * @return instance
     */
    public static function newInstanceFromPDO(\PDO $pdoConnection,
                                                   $logFileDirectory);

    /**
     * Create an instance fron user login details.
     * Need privilege to: set global variables`
     *
     * @param type $host
     * @param type $username
     * @param type $password
     * @param type $dbname
     * @param type $logFileDirectory
     * @return new instance
     */
    public static function newInstanceFromParams($host, $username, $password, $dbname,
                                                      $logFileDirectory);


    /* -----------------------------------------------------------------------
     * `mysql`.`general_log` table routines
     */

    /**
     * Tell the server to start logging to the `mysql.general_log` table
     * see: variable: `log_output`
     *                `general_log_file`
     *                `general_log`
     *
     * @param boolean $truncate
     * @return boolean
     */
    public function startLoggingToTable($truncate = true);


    /**
     * Stop tracing completely.
     * see: variable: `log_output`
     *                `general_log`
     *
     * @return boolean
     */
    public function stopLogging();

    /**
     * Truncate the `mysql.general_log` table.
     *
     * @return boolean
     */
    public function clearTableLog();

    /**
     * Extract all the current contents of the `mysql.general_log` table
     *
     * @return  array
     */
    public function extractLogTable();


    /* -----------------------------------------------------------------------
     *  Tracefile routines
     */

    /**
     * Created a new Trace filename
     *
     * @param type $id
     * @return string
     * @throws ErrorException
     */
    public function newTraceFilename($id = '');


    /**
     * Sets the trace file in the MySQL server
     * see: variable:  `general_log_file`
     *
     * @param type $fullPath
     * @return type
     * @throws \ErrorException
     */
    public function setLogFile($fullPath = '');


    /**
     * Tell the server to start logging to the trace file.
     * see: variable: `log_output`
     *                `general_log_file`
     *                `general_log`
     *
     * @param  boolean $truncate - truncate the file - default
     * @return boolean
     * @throws \Exception\InvalidArgumentException
     */
    public function startLoggingToFile($truncate = true);


    /**
     * The current Trace Filename
     *
     * @return string
     */
    public function logFile();


    /**
     * Truncate the current trace file.
     *
     * @return boolean
     */
    public function clearFileLog();

    /**
     * set the trace file directory
     *
     * @param type $dir
     */
    public function setLogFileDirectory($dir);


    /**
     * Are we currently logging?
     *
     * @return boolean
     */
    public function isLogging();

    /**
     *  Is the trace destination a File?
     *
     * @return boolean
     */
    public function isLoggingToFile();

    /**
     *  Is the trace destination the `mysql.general_log` table?
     *
     * @return boolean
     */
    public function isLoggingToTable();

    /**
     * Truncate Table and Trace file.
     */
    public function clearLogs();

    /**
     * Extract the current server `logging` variables.
     * @return array
     */
    public function currentSettings();

    /**
     * Only delete files ending in 'txt';
     */
    public function deleteAllTraceFiles($fail = false);
}