php-e107/e107_handlers/e_db_interface.php

<?php
	/**
	 * Created by PhpStorm.
	 * Date: 2/3/2019
	 * Time: 6:22 PM
	 */


	interface e_db
	{

		/**
		 * Connect ONLY  - used in v2.x
		 *
		 * @param string $mySQLserver IP Or hostname of the MySQL server
		 * @param string $mySQLuser MySQL username
		 * @param string $mySQLpassword MySQL Password
		 * @param bool   $newLink force a new link connection if TRUE. Default FALSE
		 * @return boolean true on success, false on error.
		 */
		public function connect($mySQLserver, $mySQLuser, $mySQLpassword, $newLink = false);


		/**
		 * Select the database to use.
		 *
		 * @param string       $database name
		 * @param array|string $prefix
		 * @param boolean      $multiple set to maintain connection to a secondary database.
		 * @return boolean true when database selection was successful otherwise false.
		 */
		public function database($database, $prefix = MPREFIX, $multiple=false);


		/**
		 * @param string $table
		 * @param string $arg
		 * @param bool   $debug
		 * @param string $log_type
		 * @param string $log_remark
		 * @return int number of affected rows, or false on error
		 * @desc Delete rows from a table<br />
		 * <br />
		 * Example:
		 * <code>$sql->delete("tmp", "tmp_ip='$ip'");</code><br />
		 * <br />
		 * @access public
		 */
		function delete($table, $arg = '', $debug = false, $log_type = '', $log_remark = '');





		/**
		 * @param string $type assoc|num|both
		* @return array|bool MySQL row
		* @desc Fetch an array containing row data (see PHP's mysql_fetch_array() docs)<br />
		* @example
		* Example :<br />
		* <code>while($row = $sql->fetch()){
		*  $text .= $row['username'];
		* }</code>
		*
		* @access public
		*/
		function fetch($type = null);






		/**
		 *	Determines if a plugin field (and key) exist. OR if fieldid is numeric - return the field name in that position.
		 *
		 *	@param string $table - table name (no prefix)
		 *	@param string $fieldid - Numeric offset or field/key name
		 *	@param string $key - PRIMARY|INDEX|UNIQUE - type of key when searching for key name
		 *	@param boolean $retinfo = FALSE - just returns true|false. TRUE - returns all field info
		 *	@return array|boolean - FALSE on error, field information on success
		 */
	    function field($table,$fieldid="",$key="", $retinfo = false);



		/**
		 * @param string $table
		 * @param array  $arg
		 * @param bool   $debug
		 * @param string $log_type
		 * @param string $log_remark
		 * @return int Last insert ID or false on error
		 * @desc Insert/REplace a row into the table<br />
		 * <br />
		 * Example:<br />
		 * <code>e107::getDb()->replace("links", $array);</code>
		 *
		 * @access public
		 */
		function replace($table, $arg, $debug = false, $log_type = '', $log_remark = '');







		/**
		 * Query and fetch at once
		 *
		 * Examples:
		 * <code>
		 * <?php
		 *
		 * // Get single value, $multi and indexField are ignored
		 * $string = e107::getDb()->retrieve('user', 'user_email', 'user_id=1');
		 *
		 * // Get single row set, $multi and indexField are ignored
		 * $array = e107::getDb()->retrieve('user', 'user_email, user_name', 'user_id=1');
		 *
		 * // Fetch all, don't append WHERE to the query, index by user_id, noWhere auto detected (string starts with upper case ORDER)
		 * $array = e107::getDb()->retrieve('user', 'user_id, user_email, user_name', 'ORDER BY user_email LIMIT 0,20', true, 'user_id');
		 *
		 * // Same as above but retrieve() is only used to fetch, not useable for single return value
		 * if(e107::getDb()->select('user', 'user_id, user_email, user_name', 'ORDER BY user_email LIMIT 0,20', true))
		 * {
		 *        $array = e107::getDb()->retrieve(null, null, null,  true, 'user_id');
		 * }
		 *
		 * // Using whole query example, in this case default mode is 'single'
		 * $array = e107::getDb()->retrieve('SELECT
		 *    p.*, u.user_email, u.user_name FROM `#user` AS u
		 *    LEFT JOIN `#myplug_table` AS p ON p.myplug_table=u.user_id
		 *    ORDER BY u.user_email LIMIT 0,20'
		 * );
		 *
		 * // Using whole query example, multi mode - $fields argument mapped to $multi
		 * $array = e107::getDb()->retrieve('SELECT u.user_email, u.user_name FROM `#user` AS U ORDER BY user_email LIMIT 0,20', true);
		 *
		 * // Using whole query example, multi mode with index field
		 * $array = e107::getDb()->retrieve('SELECT u.user_email, u.user_name FROM `#user` AS U ORDER BY user_email LIMIT 0,20', null, null, true, 'user_id');
		 * </code>
		 *
		 * @param string $table if empty, enter fetch only mode
		 * @param string $fields comma separated list of fields or * or single field name (get one); if $fields is of type boolean and $where is not found, $fields overrides $multi
		 * @param string $where WHERE/ORDER/LIMIT etc clause, empty to disable
		 * @param boolean $multi if true, fetch all (multi mode)
		 * @param string $indexField field name to be used for indexing when in multi mode
		 * @param boolean $debug
		 * @return string|array
		 */
		public function retrieve($table, $fields = null, $where=null, $multi = false, $indexField = null, $debug = false);


		/**
		 * @param string fields to retrieve
		 * @param bool $amount
		 * @param bool $maximum
		 * @param bool $ordermode
		 * @return array
		 * @desc returns fields as structured array
		 * @access public
		 */
		function rows($fields = 'ALL', $amount = false, $maximum = false, $ordermode=false);


		/**
		 * Function to handle any MySQL query
		 *
		 * @param string $query - the MySQL query string, where '#' represents the database prefix in front of table names.
		 *        Strongly recommended to enclose all table names in backticks, to minimise the possibility of erroneous substitutions - its
		 *            likely that this will become mandatory at some point
		 * @param bool   $debug
		 * @param string $log_type
		 * @param string $log_remark
		 * @return boolean | integer
		 *        Returns FALSE if there is an error in the query
		 *        Returns TRUE if the query is successful, and it does not return a row count
		 *        Returns the number of rows added/updated/deleted for DELETE, INSERT, REPLACE, or UPDATE
		 */
		public function gen($query, $debug = false, $log_type = '', $log_remark = '');


		/**
		 * @param string       $tableName - Name of table to access, without any language or general DB prefix
		 * @param array|string $arg (array preferred)
		 * @param bool         $debug
		 * @param string       $log_type
		 * @param string       $log_remark
		 * @return int|false number of affected rows, or false on error
		 * @desc Update fields in ONE table of the database corresponding to your $arg variable<br />
		 * <br />
		 * Think to call it if you need to do an update while retrieving data.<br />
		 * <br />
		 * Example using a unique connection to database:<br />
		 * <code>e107::getDb()->update("user", "user_viewed='$u_new' WHERE user_id='".USERID."' ");</code>
		 * <br />
		 * OR as second connection<br />
		 * <code>
		 * e107::getDb('sql2')->update("user", "user_viewed = '$u_new' WHERE user_id = '".USERID."' ");</code><br />
		 *
		 * @access public
		 */
		function update($tableName, $arg, $debug = false, $log_type = '', $log_remark = '');



		/**
		 * @desc Closes the mySQL server connection.<br />
		 * <br />
		 * Only required if you open a second connection.<br />
		 * Native e107 connection is closed in the footer.php file<br />
		 * <br />
		 * Example :<br />
		 *
		 * @access public
		 * @return void
		 */
		function close();


		/**
		 * @desc Return the total number of results on the last query regardless of the LIMIT value when SELECT SQL_CALC_FOUND_ROWS is used.
		 * @return bool
		 */
		public function foundRows();


		/**
		 * @desc Return error text for last operation
		 */
		function getLastErrorText();


		// Return error number for last operation

		/**
		 * @return mixed
		 */
		function getLastErrorNumber();


		/**
		 * @desc Perform a select query()
		 * <br />
		 * If you need more requests think to call the class.<br />
		 * <br />
		 * Example using a unique connection to database:<br />
		 * <code>e107::getDb()->select("comments", "*", "comment_item_id = '$id' AND comment_type = '1' ORDER BY comment_datestamp");</code><br />
		 * <br />
		 * OR as second connection:<br />
		 * <code>
		 * e107::getDb('sql2')->select("chatbox", "*", "ORDER BY cb_datestamp DESC LIMIT $from, ".$view, true);</code>
		 *
		 * @param        $table
		 * @param string $fields
		 * @param string $arg
		 * @param bool   $noWhere
		 * @param bool   $debug
		 * @param string $log_type
		 * @param string $log_remark
		 * @return integer Number of rows or false on error
		 */
		public function select($table, $fields = '*', $arg = '', $noWhere = false, $debug = false, $log_type = '', $log_remark = '');



		/**
		 *	@desc Determines if a table index (key) exist.
		 *	@param string $table - table name (no prefix)
		 *	@param string $keyname - Name of the key to
		 *  @param array $fields - OPTIONAL list of fieldnames, the index (key) must contain
		 *	@param boolean $retinfo = FALSE - just returns true|false. TRUE - returns all key info
		 *	@return array|boolean - FALSE on error, key information on success
		 */
		function index($table, $keyname, $fields=null, $retinfo = false);




		/**
		 * @param string $tableName - Name of table to access, without any language or general DB prefix
		 * @param        $arg
		 * @param bool   $debug
		 * @param string $log_type
		 * @param string $log_remark
		 * @return int|bool Last insert ID or false on error. When using '_DUPLICATE_KEY_UPDATE' return ID, true on update, 0 on no change and false on error.
		 * @desc Insert a row into the table<br />
		 * <br />
		 * Example:<br />
		 * <code>e107::getDb()->insert("links", "0, 'News', 'news.php', '', '', 1, 0, 0, 0");</code>
		 *
		 * @access public
		 */
		function insert($tableName, $arg, $debug = false, $log_type = '', $log_remark = '');




		/**
		 * Check if a database table is empty or not.
		 * @param $table
		 * @return bool
		 */
		function isEmpty($table);



		/**
		 * Truncate a table
		 * @param string $table - table name without e107 prefix
		 */
		function truncate($table=null);



		/**
		 * @param string $table
		 * @param string $fields
		 * @param string $arg
		 * @param bool   $debug
		 * @param string $log_type
		 * @param string $log_remark
		 * @return int number of affected rows or false on error
		 * @desc Count the number of rows in a select<br />
		 * <br />
		 * Example:<br />
		 * <code>$topics = e107::getDb()->count("forum_thread", "(*)", "thread_forum_id='".$forum_id."' AND thread_parent='0'");</code>
		 *
		 * @access public
		 */
		function count($table, $fields = '(*)', $arg = '', $debug = FALSE, $log_type = '', $log_remark = '');



		/**
		 * Return the maximum value for a given table/field
		 * @param $table (without the prefix)
		 * @param $field
		 * @param string $where (optional)
		 * @return bool|resource
		 */
		public function max($table, $field, $where='');




		/**
		 * Dump MySQL Table(s) to a file in the Backup folder.
		 * @param $table string - name without the prefix or '*' for all
		 * @param $file string - optional file name. or leave blank to generate.
		 * @param $options - additional preferences.
		 * @return string|bool backup file path.
		 */
		function backup($table='*', $file='', $options=null);


		/**
		 * TODO: Document this method
		 */
		public function resetTableList();

		/**
		 * Return a filtered list of DB tables.
		 *
		 * @param string $mode [optional] all|lan|nolan|nologs
		 * @return array
		 */
		public function tables($mode='all');



		/**
		 * @desc Returns the number of columns in the result set
		 * @return mixed
		 */
		public function columnCount();


		/**
		 * Set the current database language
		 * @param string $lang English, French etc.
		 * @return null
		 */
		public function setLanguage($lang);



		/**
		 * Get the current database language
		 * @return string $lang English, French etc.
		 */
		public function getLanguage();



		/**
		 * XXX: e_db_pdo and e_db_mysql have differing implementations of this method.
		 * @param string $oldtable
		 * @param string $newtable
		 * @param bool $drop
		 * @param bool $data
		 * @return bool|int|PDOStatement|resource
		 */
		public function copyTable($oldtable, $newtable, $drop = false, $data = false);



		/**
		 * Drop/delete table and all it's data
		 * @param string $table name without the prefix
		 * @return bool|int
		 */
		public function dropTable($table);




		/**
		 * Returns the last database query used.
		 * @return string
		 */
		function getLastQuery();

}