<?

/**
 * This file contains classes used to aid in IO operations
 *
 * This file provides classes used to aid in IO operations performed by 
 * various aspects of Emailr.  This is most commonly seen during the 
 * parsing of mail files within mail folders, moving mails from their 
 * respective inbox to the parsed folders, etc.
 * @package Emailr
 * @subpackage Common
 * @author Jon Herron
 * @version 0.0.0.1
 * @since 02.23.2008
 */


require_once realpath(dirname(__file__) . "/BaseClasses.inc");

/**
 * Class used to aid in directory browsing and iterating over files within.
 *
 * This class will provide methods to aid in the browsing of directories and 
 * iterating over files within.  This is most heavily used during the reading 
 * of inboxes and their mails contained within.
 * @author Jon Herron
 * @package Emailr
 * @subpackage Common
 * @version 0.0.0.1
 * @since 02.23.2008
 */
class DirectoryBrowser extends EmailrBase
{
	/**
	 * Private data member to hold a bool value to indicate if a directory has been parsed.
	 * @access private
	 * @var array
	 * @author Jon Herron
	 * @version 0.0.0.1
	 * @since 02.23.2008
	 */
	private $_directoryParsed;

	/**
	 * Private data member to hold an array of file names.
	 * @access private
	 * @var array
	 * @author Jon Herron
	 * @version 0.0.0.1
	 * @since 02.23.2008
	 */
	private $_files;

	/**
	 * Private data member to hold a bool value to indicate to perform an is valid file check.
	 * @access private
	 * @var bool
	 * @author Jon Herron
	 * @version 0.0.0.1
	 * @since 02.23.2008
	 */
	private $_performFileCheck;
	
	/**
	 * Public constructor for the DirectoryBrowser
	 *
	 * This public constructor will create a new instance of the DirectoryBrowser 
	 * class.
	 * @access public
	 * @author Jon Herron
	 * @returns DirectoryBrowser class instance
	 * @version 0.0.0.1
	 * @since 02.23.2008
	 */
	public function DirectoryBrowser()
	{
		parent::EmailrBase();

		// log the fact that we are in the constructor
		$this->_logger->Info("Inside DirectoryBrowser constructor");

		// call the clear function, which will default the class it is original 
		// state.  This will ensure a new object is the same as an existing object 
		// that has been cleared.
		$this->Clear();
	}

	/**
	 * Public function to clear the class instance
	 *
	 * This public function will return a class instance to its default state, setting all 
	 * private data members back to their original default state.
	 * @access public
	 * @author Jon Herron
	 * @version 0.0.0.1
	 * @since 02.23.2008
	 */
	public function Clear()
	{
		$this->_logger->Info("Inside DirectoryBrowser->Clear");

		// set directory parsed to false
		$this->_directoryParsed = false;

		$this->_logger->Debug("_directoryParsed = false");

		// set our file list to a new array
		$this->_files = array();

		$this->_logger->Debug("_files = $this->_files (count = " . count($this->_files) . ")");

		// default perform file check to true
		$this->_performFileCheck = true;
		
		$this->_logger->Debug("_performFileCheck = $this->_performFileCheck");
		$this->_logger->Info("Leaving DirectoryBrowser->Clear");
	}

	/**
	 * Public function to retrieve number of files contained in the parsed directory
	 *
	 * This public function will first check to make sure that a directory has been 
	 * parsed, before trying to return the array of files.  If this has not occured, 
	 * an exception will be thrown.  If ParseDirectory was successfully called, a  
	 * count of file names will be returned.
	 * @access public
	 * @author Jon Herron
	 * @version 0.0.0.1
	 * @since 02.23.2008
	 */
	public function GetFileCount()
	{

		// make sure we have already parsed a directory
		if($this->_directoryParsed)
		{
			// everything looks good, return the count of files
			return(count($this->_files));
		}
		else
		{
			// we have not, need to throw an exception
			throw new Exception("Need to call ParseDirectory prior to GetFileCount");
		}
	}

	/**
	 * Public function to retrieve files contained in the parsed directory
	 *
	 * This public function will first check to make sure that a directory has been 
	 * parsed, before trying to return the array of files.  If this has not occured, 
	 * an exception will be thrown.  If ParseDirectory was successfully called, an 
	 * array of file names will be returned.
	 * @access public
	 * @author Jon Herron
	 * @version 0.0.0.1
	 * @since 02.23.2008
	 */
	public function GetFiles()
	{
		$this->_logger->Info("Inside DirectoryBrowser->GetFiles");

		// make sure we have already parsed a directory
		if($this->_directoryParsed)
		{
			$this->_logger->Debug("_directoryParsed = $this->_directoryParsed");
			$this->_logger->Debug("Returning _files = $this->_files - count = (" . count($this->_files) . ")");

			// everything looks good, return the array of files
			return($this->_files);
		}
		else
		{
			$this->_logger->Error("Call to GetFiles prior to ParseDirectory");

			// we have not, need to throw an exception
			throw new Exception("Need to call ParseDirectory prior to GetFiles");
		}
		
		$this->_logger->Info("Leaving DirectoryBrowser->GetFiles");
	}

	/**
	 * Public function to parse a directory, reading all the files contained within
	 *
	 * This public function will parse the passed in directory path, reading each of the 
	 * files contained within.  If $performFileCheck is either not set, or explicitly 
	 * set to true, each entry in the directory will be checked to make sure it is a valid 
	 * file.  This helps to ensure . and .. are not treated as files.
	 * @access public
	 * @author Jon Herron
	 * @version 0.0.0.1
	 * @since 02.23.2008
	 */
	public function ParseDirectory($directoryPath, $performFileCheck = true)
	{
		$this->_logger->Info("Inside DirectoryBrowser->ParseDirectory");
		$this->_logger->Debug("directoryPath = $directoryPath");
		$this->_logger->Debug("performFileCheck = $performFileCheck");

		// first make sure we have a valid file, if not throw an exception
		if(is_dir($directoryPath))
		{
			$this->_logger->Debug("directoryPath is a valid directory");
			
			// directory path seems to be valid, read out each file from the directory
			$this->_files = scandir($directoryPath);

			$this->_logger->Debug("directoryPath scanned, _files = $this->_files - (count = " . count($this->_files) . ")");

			// set our flag to say whether or not we should check for valid files
			$this->_performFileCheck = $performFileCheck;

			$this->_logger->Debug("_performFileCheck = $this->_performFileCheck");

			// if we need to perform a valid file check, do so now
			if($this->_performFileCheck)
			{
				// loop backwards through the files so that unset does not 
				// disturbe our iterator.
				for($i = (count($this->_files) -1); $i >=0; $i--)
				{
					// are we looking at a valid file?
					if(!is_file($directoryPath . "/" . $this->_files[$i]))
					{
						$this->_logger->Debug("Removing " . $this->_files[$i] . " from _files");

						// no we are not, remove it from the array
						unset($this->_files[$i]);
					}
				}
			}

			// signal that a directory has been parsed
			$this->_directoryParsed = true;

			$this->_logger->Debug("_directoryParsed = $this->_directoryParsed");
		}
		else
		{
			$this->_logger->Error("directoryPath is not a valid directory - $directoryPath");

			// an invalid directory path was passed in, throw an exception
			throw new Exception("$directoryPath is not a valid directory path");
		}
		
		$this->_logger->Info("Leaving DirectoryBrowser->ParseDirectory");
	}
}

?>