<?php

/**
 * IWP implementation of Interspire Stash - borrowed from IEM
 *
 * The implementation will allow caching of commonly used variables to a file.
 * 
 * Ported for use with IWP.
 *
 * @author Hendri <hendri@interspire.com>
 * @author Gwilym Evans <gwilym.evans@interspire.com>
 *
 * @package API
 */

/**
 * Include base library
 */

IWP::GetLib('interspire_stash/interspirestash');

/**
 * iwp_eventstash class
 *
 * The IEM Interspire Stash class is designed to handle caching of commonly used variables
 * that require presistant storage. It is designed so that it can restore it self
 * in the event that the cache data files were deleted.
 *
 * Limitation at this stage is that it can only hold data of up to ~16.7 million bytes (ie. characters)
 *
 * @package API
 */
class iwp_eventstash extends iwp_base implements InterspireStash
{
	/**
	 * The number of backup this class should make
	 */
	const BACKUP_COUNT = 2;


	/**
	 * Singleton instance of this class
	 * @var iwp_eventstash iwp_eventstash
	 */
	static private $_instance = null;


	/**
	 * Cached data
	 * @var Array Cached data
	 */
	private $_data = null;

	/**
	 * Database object to be used to query the database server
	 * @var Db Database object
	 */
	private $_db = null;
	
	/**
	 * Path to stash file.
	 * @var String Path to stash file.
	 */
	public $stashFile = null;

	/**
	 * getInstance
	 * Get an instance of this class (Provide singleton access to this class)
	 * @return iwp_eventstash Returns current instance of this class
	 */
	static public function getInstance()
	{
		if (is_null(self::$_instance)) {
			self::$_instance = new iwp_eventstash();
		}

		return self::$_instance;
	}

	/**
	 * CONSTRUCTOR
	 * Constructor for this class
	 *
	 * Attempt to load data from data file:
	 * - If data file does not exits, it will try to load it from backup data file
	 * - If data file exists, but cannot be read/write, it will throw an exception
	 *
	 * @throws InterspireStashException
	 *
	 * @return iwp_eventstash Returns an instance of this object
	 *
	 * @uses InterspireStashException
	 * @uses InterspireStashException::CANNOT_WRITE_DATA
	 * @uses InterspireStashException::CANNOT_READ_DATA
	 *
	 * @todo test
	 */
	private function __construct()
	{
		$this->stashFile = IWP_CACHE_PATH . '/stash';
		
		$fileName = $this->stashFile . '.php';
		if (file_exists($fileName)) {
			if (!is_readable($fileName)) {
				throw new InterspireStashException('Data file cannot be read', InterspireStashException::CANNOT_READ_DATA);
			}

			if (!is_writable($fileName)) {
				throw new InterspireStashException('Data file cannot be written to', InterspireStashException::CANNOT_WRITE_DATA);
			}
		}

		if (!$this->_loadFromFile()) {
			$this->_data = array();
			$this->_writeToFile();
		}
	}

	/**
	 * read
	 * This method will get data for the given key value
	 *
	 * @param String $key Key associated with the data to be fetched
	 *
	 * @throws InterspireStashException
	 *
	 * @return Mixed Returns key value
	 *
	 * @uses InterspireStashException
	 * @uses InterspireStashException::CANNOT_READ_DATA
	 * @uses InterspireStashException::KEY_NOT_EXISTS
	 *
	 * @todo testing
	 */
	public function read($key)
	{
		if (!$this->exists($key)) {
			throw new InterspireStashException('Key does not exists', InterspireStashException::KEY_NOT_EXISTS);
		}

		return $this->_data[$key];
	}

	/**
	 * write
	 * This method will store data for a given key value
	 *
	 * @param String $key Key to be associated with the data
	 * @param Mixed $value Data to be stored
	 * @param Boolean $overwrite Overwrite existing data (OPTIONAL, Default = FALSE)
	 *
	 * @throws InterspireStashException
	 *
	 * @return Void Returns nothing
	 *
	 * @uses InterspireStashException
	 * @uses InterspireStashException::CANNOT_WRITE_DATA
	 * @uses InterspireStashException::KEY_EXISTS
	 *
	 * @todo test
	 */
	public function write($key, $data, $overwrite = false)
	{
		if ((!$overwrite) && ($this->exists($key))) {
			throw new InterspireStashException('Key exists', InterspireStashException::KEY_EXISTS);
		}

		$this->_data[$key] = $data;
		$this->_writeToFile();
	}

	/**
	 * exists
	 * Check whether or not data with specified key exists
	 *
	 * @param String $key Key associated with the data
	 *
	 * @throws InterspireStashException
	 *
	 * @return Boolean Returns TRUE if data exists, FALSE otherwise
	 *
	 * @uses InterspireStashException
	 * @uses InterspireStashException::CANNOT_READ_DATA
	 *
	 * @todo test
	 */
	public function exists($key)
	{
		return array_key_exists($key, $this->_data);
	}


	/**
	 * remove
	 * Remove data associated with sepecified key
	 *
	 * @param String $key Key associated with the data to be removed
	 *
	 * @throws InterspireStashException
	 *
	 * @return Void Returns nothing
	 *
	 * @uses InterspireStashException
	 * @uses InterspireStashException::KEY_NOT_EXISTS
	 * @uses InterspireStashException::CANNOT_WRITE_DATA
	 *
	 * @todo test
	 */
	public function remove($key)
	{
		if (!$this->exists($key)) {
			throw new InterspireStashException('Key not found', InterspireStashException::KEY_NOT_EXISTS);
		}

		unset($this->_data[$key]);
		$this->_writeToFile();
	}

	/**
	 * _loadFromFile
	 * This function will load data from specified data file
	 * If file not found, attempt to load from backup file
	 *
	 * @throws InterspireStashException
	 * @return Boolean Returns TRUE if file is loaded, FALSE otherwise
	 *
	 * @uses InterspireStashException
	 * @uses InterspireStashException::CANNOT_WRITE_DATA
	 */
	private function _loadFromFile()
	{
		$loaded = false;

		for ($i = 0; $i < self::BACKUP_COUNT; ++$i) {
			$fileName = $this->stashFile . ($i != 0? '.backup_' . $i : '') . '.php';
			if (!file_exists($fileName)) {
				continue;
			}

			$contents = file_get_contents($fileName);
			if ($contents === false) {
				continue;
			}

			$this->_data = unserialize(substr($contents, 8));
			$loaded = true;

			// Copy back the backup data file to the default data file
			if (($i != 0) && (!copy($fileName, $this->stashFile . '.php'))) {
				throw InterspireStashException('Cannot write to "Stash" data file', InterspireStashException::CANNOT_WRITE_DATA);
			}

			break;
		}

		return $loaded;
	}

	/**
	 * _writeToFile
	 * This function will write data to specified file.
	 * It will also create backup of the existing data to backup files
	 *
	 * @throw InterspireStashException
	 *
	 * @return Void Does not return anything
	 *
	 * @uses InterspireStashException
	 * @uses InterspireStashException::CANNOT_WRITE_DATA
	 */
	private function _writeToFile()
	{
		if (!file_put_contents($this->stashFile . '.php', '<?php /*' . serialize($this->_data)) > 0) {
			throw new InterspireStashException('Cannot write to "Stash" data file', InterspireStashException::CANNOT_WRITE_DATA);
		}

		@chmod($this->stashFile . '.php', 0666);

		/**
		 * Make a copy of data file
		 */
		for ($i = 1; $i <= self::BACKUP_COUNT; ++$i) {
			$fileName = $this->stashFile . '.backup_' . $i . '.php';
			copy($this->stashFile . '.php', $fileName);
			@chmod($fileName, 0666);
		}
	}
}