<?php
/*=====================================================================*\
|| ###################################################################
|| # Blue Static ISSO Framework
|| # Copyright Š2002-[#]year[#] Blue Static
|| #
|| # This program is free software; you can redistribute it and/or modify
|| # it under the terms of the GNU General Public License as published by
|| # the Free Software Foundation; version [#]gpl[#] of the License.
|| #
|| # This program is distributed in the hope that it will be useful, but
|| # WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
|| # or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
|| # more details.
|| #
|| # You should have received a copy of the GNU General Public License along
|| # with this program; if not, write to the Free Software Foundation, Inc.,
|| # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
|| ###################################################################
\*=====================================================================*/

/**
* Abstract Database Layer (Db.php)
*
* @package	ISSO
*/

require_once('ISSO/Functions.php');

/**
* Abstract Database Layer
*
* This class provides an abstract template for all RDBMS layers. All
* ISSO abstraction layers should inherit this class. It provides error
* reporting, SQL analysis, and general connection functionality.
*
* Constants:
*		ISSO_SHOW_QUERIES_LIVE - Show queries in page output as they are sent
*
* @author		Blue Static
* @copyright	Copyright Š2002 - [#]year[#], Blue Static
* @version		$Revision$
* @package		ISSO
* 
*/
abstract class BSDb
{
	/**
	* Determines whether or not errors should be shown
	* @var	bool
	*/
	public $showerrors = true;
	
	/**
	* Current error number
	* @var	integer
	*/
	protected $errnum = 0;
	
	/**
	* Description of current error
	* @var	string
	*/
	protected $errstr = '';
	
	/**
	* Currend open database connection
	* @var	integer
	*/
	protected $dblink = null;
	
	/**
	* Current query ID
	* @var	integer
	*/
	protected $result = null;
	
	/**
	* Current query string
	* @var	string
	*/
	protected $querystr = '';
	
	/**
	* History of all executed queryies
	* @var	array
	*/
	protected $history = array();
	
	// ###################################################################
	/**
	* Returns the history information array
	*
	* @return	array	History record
	*/
	public function getHistory()
	{
		return $this->history;
	}
	
	// ###################################################################
	/**
	* Connect to a the specified database
	*
	* @param	string	Server name
	* @param	string	User name
	* @param	string	Password
	* @param	string	Database name
	* @param	bool	Use p-connect?
	*
	* @return	bool	Result of connect
	*/
	public function connect($server, $user, $password, $database, $pconnect)
	{
		if ($this->dblink == false)
		{
			$this->dblink = $this->{($pconnect ? '_connect' : '_pConnect')}($server, $user, $password, $database);
			
			if ($this->dblink == false)
			{
				$this->_error('DB-Link == false, cannot connect');
				return false;
			}
			
			return true;
		}
	}
	
	/**
	* Abstract function that returns a database link after establishing a connection. This just
	* calls the function and does not do any checking
	*
	* @param	string	Server name
	* @param	string	User name
	* @param	string	Password
	* @param	string	Database name
	*
	* @return	integer	Database link
	*/
	protected abstract function _connect($server, $user, $password, $database);
	
	/**
	* Abstract function that returns a database link after establishing a connection. This just
	* calls the function and does not do any checking
	*
	* @param	string	Server name
	* @param	string	User name
	* @param	string	Password
	* @param	string	Database name
	*
	* @return	resource	Database link
	*/
	protected abstract function _pConnect($server, $user, $password, $database);
	
	// ###################################################################
	/**
	* Send a query to the open database link
	*
	* @param	string	Query string
	*
	* @return	integer	Result
	*/
	public function query($string)
	{
		$time = microtime();
		
		$this->querystr = $string;
		$this->result = $this->_query($string);
				
		if (!$this->result)
		{
			$this->_error('Invalid SQL query');
		}
		
		$this->history[] = $history = array('query' => $string, 'time' => BSFunctions::FetchMicrotimeDiff($time), 'trace' => $this->_formatBacktrace(debug_backtrace()));
		
		if (defined('ISSO_SHOW_QUERIES_LIVE'))
		{
			if (constant('ISSO_SHOW_QUERIES_LIVE'))
			{
				print($this->_constructDebugQuery($history));
			}
		}
		
		return $this->result;
	}
	
	/**
	* Abstract function that executes the query command on the database
	*
	* @param	string	Query string
	*
	* @return	integer	Result ID
	*/
	protected abstract function _query($query);
	
	// ###################################################################
	/**
	* Escape a string (depending on character set, if supported)
	*
	* @param	string	String to be escaped
	*
	* @return	string	Escaped string
	*/
	public function escapeString($string)
	{
		return $this->_escapeString($string);
	}
	
	/**
	* Abstract function that calls the escape_string() method
	*
	* @param	string	String to escape
	*
	* @return	string	Escaped string
	*/
	protected abstract function _escapeString($string);
	
	// ###################################################################
	/**
	* Escapes a binary string for insertion into the database
	*
	* @param	string	Unescaped data
	*
	* @return	string	Escaped binary data
	*/
	public function escapeBinary($binary)
	{
		return $this->_escapeBinary($binary);
	}
	
	/**
	* Abstract function that calls escape_binary()
	*
	* @param	string	Binary to escape
	*
	* @return	string	Escaped binary
	*/
	protected abstract function _escapeBinary($string);
	
	// ###################################################################
	/**
	* Unescapes a binary string that was fetched from the database
	*
	* @param	string	Escaped data
	*
	* @return	string	Unescaped binary data
	*/
	public function unescapeBinary($binary)
	{
		return $this->_unescapeBinary($binary);
	}
	
	/**
	* Abstract function that calls unescape_binary()
	*
	* @param	string	Escaped data
	*
	* @return	string	Data that has been unescaped
	*/
	protected abstract function _unescapeBinary($string);
	
	// ###################################################################
	/**
	* Fetch the query result as an array
	*
	* @param	integer	Result
	* @param	bool	Return an associative array?
	*
	* @return	array	A row of the query result
	*/
	public function fetchArray($result, $assoc = true)
	{
		return $this->{($assoc ? '_fetchAssocArray' : '_fetchRowArray')}($result);
	}
	
	/**
	* Abstract function that returns an associative array of given result
	*
	* @param	integer	Result
	*
	* @return	array	Result array
	*/
	protected abstract function _fetchAssocArray($result);
	
	/**
	* Abstract function that returns a row array of given result
	*
	* @param	integer	Result
	*
	* @return	array	Result array
	*/
	protected abstract function _fetchRowArray($result);
	
	// ###################################################################
	/**
	* Fetch the query result as an object
	*
	* @param	integer	Result
	*
	* @return	object	An object with the query result
	*/
	public function fetchObject($result)
	{
		return $this->_fetchObject($result);
	}
	
	/**
	* Abstract function that returns an object for a given result
	*
	* @param	integer	Result
	*
	* @return	object	Row object
	*/
	public abstract function _fetchObject($result);
	
	// ###################################################################
	/**
	* Send a query and return the first row of the results
	*
	* @param	string	Query string
	* @param	string	Result return function (in the database layer)
	*
	* @return	mixed	Results in variable formats
	*/
	public function queryFirst($string, $callback = 'fetchArray')
	{
		$resource = $this->query($string);
		if ($resource)
		{
			$return = $this->$callback($resource);
			$this->_freeResult($resource);
			return $return;
		}
		else
		{
			return false;
		}
	}
	
	// ###################################################################
	/**
	* Free the current query result
	*
	* @param	integer	Result
	*/
	public function freeResult($result)
	{
		$this->_freeResult($result);
		$this->result = null;
		$this->querystr = '';
	}
	
	/**
	* Abstract function that frees a given result
	*
	* @param	integer	Result ID
	*/
	protected abstract function _freeResult($result);
	
	// ###################################################################
	/**
	* Fetch the unique ID of the record just inserted
	*
	* @return	integer	Insert-ID
	*/
	public function insertId()
	{
		return $this->_insertID();
	}
	
	/**
	* Abstract function that returns the ID of the most recently-inserted
	* record
	*
	* @return	integer	Insertion ID
	*/
	protected abstract function _insertId();
		
	// ###################################################################
	/**
	* Fetch the number of rows in the result
	*
	* @param	integer	Result
	*
	* @return	integer	Number of rows
	*/
	public function numRows($result)
	{
		return $this->_numRows($result);
	}
	
	/**
	* Abstract function that returns the number of rows in the result
	*
	* @param	integer	Result ID
	*
	* @return	integer	Number of rows
	*/
	protected abstract function _numRows($result);
	
	// ###################################################################
	/**
	* Fetch the number of rows affected by the query
	*
	* @param	integer	Result
	*
	* @return	integer	Number of affected rows
	*/
	public function affectedRows($result)
	{
		return $this->_affectedRows($result);
	}
	
	/**
	* Abstract function that returns the number of affected rows in the result
	*
	* @param	integer	Result ID
	*
	* @return	integer	Number of rows
	*/
	protected abstract function _affectedRows($result);
	
	// ###################################################################
	/**
	* Returns the errror number
	*/
	public abstract function _errorNumber();
	
	/**
	* Returns the error string
	*/
	public abstract function _errorString();
	
	// ###################################################################
	/**
	* Sends the command to start a transaction. This command should never
	* be reached as it's always overridden
	*/
	public abstract function transactionStart();
	
	// ###################################################################
	/**
	* Sends the command to set this as a savepoint. This command should never
	* be reached as it's always overridden
	*
	* @param	string	Named savepoint
	*/
	public abstract function transactionSavepoint($name);
	
	// ###################################################################
	/**
	* Sends the command to rollback to a given savepoint. This command
	* should never be reached as it's always overridden
	*
	* @param	string	Named savepoint
	*/
	public abstract function transactionRollback($name = null);
	
	// ###################################################################
	/**
	* Sends the command to commit the entire transaction. This command
	* should never be reached as it's always overridden
	*/
	public abstract function transactionCommit();
	
	// ###################################################################
	/**
	* Error wrapper for ISSO->message()
	*
	* @param	string	User defined error message
	*/
	protected function _error($message)
	{
		if ($this->showerrors)
		{
			if ($this->dblink)
			{
				$this->errnum = $this->_errorNumber();
				$this->errstr = $this->_errorString();
			}
			
			$style['code'] = 'font-family: \'Courier New\', Courier, mono; font-size: 11px;';
			
			$message_prepped = "<blockquote>\n<p>";
			$message_prepped .= "\n\t&raquo; <strong>Query:</strong>\n<br /> <pre style=\"$style[code]\">" . htmlspecialchars($this->querystr) ."</pre>\n<br />";
			$message_prepped .= "\n\t&raquo; <strong>Error Number:</strong> <span style=\"$style[code]\">" . $this->errnum . "</span>\n<br />";
			$message_prepped .= "\n\t&raquo; <strong>Error Message:</strong> <span style=\"$style[code]\">" . $this->errstr . "</span>\n<br />";
			$message_prepped .= "\n\t&raquo; <strong>Additional Notes:</strong> <span style=\"$style[code]\">" . $message . "</span>\n<br />";
			$message_prepped .= "\n\t&raquo; <strong>File:</strong> <span style=\"$style[code]\">" . $_SERVER['PHP_SELF'] . "</span>\n";
			$message_prepped .= "\n</p>\n</blockquote>";
			
			BSRegister::Message('Database Error in `<em>' . BSRegister::GetApplication() . '</em>`', $message_prepped, 3);
			exit;
		}
	}
	
	// ###################################################################
	/**
	* A backtrace formatter.
	*
	* This is very slightly modified from PEAR/PHP_Compat (PHP license)
	*
	* @author	Laurent Laville <pear@laurent-laville.org>
	* @author	Aidan Lister <aidan@php.net>
	*
	* @param	array	The backtrace from debug_backtrace() to format
	*
	* @return	string	Formatted output
	*/
	private function _formatBacktrace($backtrace)
	{
		// Unset call to debug_print_backtrace
		array_shift($backtrace);
		if (empty($backtrace))
		{
			return '';
		}

		// Iterate backtrace
		$calls = array();
		foreach ($backtrace AS $i => $call)
		{
			if (!isset($call['file']))
			{
				$call['file'] = '(null)';
			}
			if (!isset($call['line']))
			{
				$call['line'] = '0';
			}
			$location = $call['file'] . ':' . $call['line'];
			$function = (isset($call['class'])) ? $call['class'] . (isset($call['type']) ? $call['type'] : '.') . $call['function'] : $call['function'];
			
			$params = '';
			if (isset($call['args']))
			{
				$args = array();
				foreach ($call['args'] AS $arg)
				{
					if (is_array($arg))
					{
						$args[] = print_r($arg, true);
					}
					elseif (is_object($arg))
					{
						$args[] = get_class($arg);
					}
					else
					{
						$args[] = $arg;
					}
				}
				$params = implode(', ', $args);
			}

			$calls[] = sprintf('#%d	 %s(%s) called at [%s]', $i, $function, $params, $location);
		}

		return implode("\n", $calls);
	}
}

/*=====================================================================*\
|| ###################################################################
|| # $HeadURL$
|| # $Id$
|| ###################################################################
\*=====================================================================*/
?>