<?

/**
 * @copyright Copyright Up and Running 
 */


/**
 * 
 * The file class provides an abstraction of a file on the file system. The common interface is used in other parts of the framework that utilize files.
 * 
 * @since 7/19/2007
 * @author Pete Hanson <peteh@uarss.com>
 */

class ems_file_file implements ems_file_interface_file,ems_file_interface_extension,ems_file_interface_filemanager
{
    /**
     * The system registry object
     * 
     * @var ems_framework_registry
     * @access protected
     */
    protected $param;

    /**
     * The folder object that contains this file
     * 
     * @var ems_file_interface_folder
     * @access protected
     */
    protected $folder;

    /**
     * The name of the file
     * 
     * @var string
     * @access protected
     */
    protected $filename;

    /**
     * The mimetype string of the file, as generated from the linux file command.
     * 
     * @var string
     * @access protected
     */
    protected $mimetype;

    /**
     * The raw size in bytes as calculated from filesize.
     * 
     * @var int
     * @access protected
     */
    protected $rawsize;

    /**
     * A formatted size that is suitable to displaying in UIs.
     * 
     * @var string
     * @access protected
     */
    protected $size;
    
    /**
     * An internal code for the filetype as defined from the mimetype. This is used to request additional type properties from the filetype system.
     * 
     * @var int
     * @access protected
     */
    protected $filecode;

    /**
     * The name of a file to be used when it's downloaded. This is normally the same as $fileName, though it can be overridden by the setter method.
     * 
     * @var string
     * @access protected
     */
    protected $downloadFileName;

    /**
     * Constructor object for the class
     * 
     * @param ems_framework_registry $param 
     * @access public
     * @return void
     */
    public function __construct(ems_framework_registry $param,$filename,$folder)
    {
	$this->param = $param;
	$this->setDefaultValues();

	$this->setFileName($filename);
	$this->setFolder($folder);
	$this->verifyFile();
    }
    
    /**
     * Initializes the properties of the class to their defaults.
     * 
     * @access private
     * @return void
     */
    private function setDefaultValues()
    {
	$this->filename = null;
	$this->folder = null;
	
	$this->mimetype = null;
	$this->rawsize = null;
	$this->size = null;
	$this->filecode = null;

	$this->downloadFileName = null;
    }
    
    /**
     * Sets a passed folder object as the folder that contains the file.
     * 
     * @param ems_file_interface_folder
     * @access protected
     * @return void
     */
    protected function setFolder(ems_file_interface_folder $folder)
    {
	$this->folder = $folder;
    }

    /**
     * Sets the filename for the file object
     * 
     * @param string
     * @access protected
     * @return void
     */
    protected function setFileName($value)
    {
	$this->filename = $value;
    }

    /**
     * This confirms that the folder path specified in the folder object and the realpath to the file are within the same folder tree. It prevents a lot of access attacks through specifying relative paths to sensitive files or access to another facility's folder structure.
     * 
     * @param none
     * @access protected
     * @return void
     */
    protected function verifyFile()
    {
	$fullPath = realpath($this->getFullPath());
	$hostRoot = realpath($this->folder->getRoot());

	if (strpos($fullPath,$hostRoot) === false)
	{
	    throw new exception("File resolved to an unauthorized part of the website.");
	}
    }

    /**
     * This sets the download file name, overriding the default of using the actual file name. This is useful if a file name is an ID number and you want to use a textual description for the name when wrapped in a download script.
     * 
     * @param string
     * @access public
     * @return void
     */
    public function setDownloadFileName($value)
    {
	$this->downloadFileName = $value;
    }

    /**
     * This gets the download file name and if it isn't present, gets the actual file name.
     * 
     * @param none
     * @access public
     * @return string
     */
    public function getDownloadFileName()
    {
	if ($this->downloadFileName !== null)
	{
	    return $this->downloadFileName;
	}
	else
	{
	    return $this->getFileName();
	}
    }

    /**
     * This gets the folder object that belongs to this file
     * 
     * @param none
     * @access public
     * @return ems_file_interface_folder
     */
    public function getFolder()
    {
	return $this->folder;
    }

    /**
     * This returns the file name
     * 
     * @param none
     * @access public
     * @return string
     */
    public function getFileName()
    {
	return $this->filename;
    }

    /**
     * This returns the full path of the file, from the root of the folder tree.
     * 
     * @param none
     * @access public
     * @return string
     */
    public function getFullPath()
    {
	return $this->getFolder()->getPath() . "/" . $this->getFileName();
    }

    /**
     * This returns the full web URL from the root web folder, generally in the format /host/<facility host>/....
     * 
     * @param none
     * @access public
     * @return string
     */
    public function getWebURL()
    {
	return $this->getFolder()->getWebPath() . "/" . $this->getFileName();	
    }

    /**
     * This returns the raw size of the file in bytes.
     * 
     * @param none
     * @access public
     * @return int
     */
    public function getRawSize()
    {
	if ($this->rawsize === null)
	{
	    $this->rawsize = filesize($this->getFullPath());
	}

	return $this->rawsize;
    }

    /**
     * This returns a nicely formatted size for use in UIs.
     * 
     * @param none
     * @access public
     * @return string
     */
    public function getSize()
    {
	if ($this->size === null)
	{
	    $niceSize = $this->param->factory->file->createNiceSize($this->getRawSize());	
	    $this->size = $niceSize->getSize();
	}
	return $this->size;
    }

    /**
     * This returns the mime type string for the file
     * 
     * @param none
     * @access public
     * @return string
     */
    public function getMimeType()
    {
	if ($this->mimetype === null)
	{
	    $utils = $this->param->factory->file->createUtils();
	    $this->mimetype = $utils->getMimeType($this->getFullPath());
	}

	return $this->mimetype;
    }

    /**
     * This returns the file type code set for this file
     * 
     * @param none
     * @access public
     * @return int
     */
    public function getTypeCode()
    {
	$mimetype = $this->getMimeType();

	if ($this->filecode === null)
	{
	    $ft = $this->param->factory->file->createFileType($mimetype);
	    $this->filecode = $ft->getCode();
	}
	return $this->filecode;
    }

    /**
     * This method deletes the file from the file system. Returns true if successful or false on an error.
     * 
     * @param none
     * @access public
     * @return boolean
     */
    public function delete()
    {
	if (@unlink($this->getFullPath()))
	{
	    return true;
	}
	else
	{
	    return false;
	}
    }

    /**
     * This method opens the file and returns all the content, essentially catting the file.
     * 
     * @param none
     * @access public
     * @return mixed
     */
    public function getFileContents()
    {
	$contents = file_get_contents($this->getFullPath());	 
	if ($contents === false)
	{
	    return null;
	}
	else
	{
	    return $contents;
	}
    }

    /**
     * This returns the file's extension
     * 
     * @param none
     * @access public
     * @return string
     */
    public function getExtension()
    {
	$parts = pathinfo($this->getFullPath());
	return $parts['extension'];
    }

    /**
     * This retrives an <img> tag that references the icon for the mimetype of the file.
     * 
     * @param none
     * @access public
     * @return string
     */
    public function getIcon()
    {
	$ft = $this->param->factory->file->createFileType($this->getMimeType());
	$imageName = $ft->getImageName();
	$temp = "<img src='/share/filemanager/files/{$imageName}' />";
	return $temp;
    }


    /**
     * This method is part of the file manager interface that the file object supports. It returns an ID string that the file manager needs to identify an item.
     * 
     * @param none
     * @access public
     * @return string
     */
    public function getFileManagerID()
    {
	return $this->getFileName();	
    }

    /**
     * This method is part of the file manager interface that the file object supports. It returns the display name for this item.
     * 
     * @param none
     * @access public
     * @return string
     */
    public function getFileManagerName()
    {
	return $this->getFileName();	
    }

    /**
     * This method is part of the file manager interface that the file object supports. It returns the type for this item.
     * 
     * @param none
     * @access public
     * @return string
     */
    public function getFileManagerType()
    {
	return $this->getMimeType();	
    }

    /**
     * This method is part of the file manager interface that the file object supports. It returns the size for this item.
     * 
     * @param none
     * @access public
     * @return string
     */
    public function getFileManagerSize()
    {
	return $this->getSize();	
    }

    /**
     * This method is part of the file manager interface that the file object supports. It returns the icon <img> tag for this item.
     * 
     * @param none
     * @access public
     * @return string
     */
    public function getFileManagerIcon()
    {
	return $this->getIcon();
    }

    /**
     * This method is part of the file manager interface that the file object supports. It defines if this item is a folder object or not.
     * 
     * @param none
     * @access public
     * @return string
     */
    public function getFileManagerIsFolder()
    {
	return false;
    }

}
?>