<?php
/*=====================================================================*\
|| ###################################################################
|| # Blue Static ISSO Framework
|| # Copyright (c)2005-2009 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 2 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
|| ###################################################################
\*=====================================================================*/

/**
 * Static functions (Functions.php)
 *
 * @package	ISSO
 */

/**
 * Functions
 *
 * This is a bunch of static functions wrapped in a class for modularity and
 * namespace collisions.
 *
 * @author		Blue Static
 * @copyright	Copyright (c)2005 - 2009, Blue Static
 * @package		ISSO
 * 
 */
class BSFunctions
{
	/**
	 * Make class static
	 */
	private function __construct()
	{}
	
	/**
	 * Sets a cookie in the user's computer/browing session
	 *
	 * @param	string	Name of the cookie
	 * @param	string	Value of the cookie
	 * @param	integer	Timeout in seconds for non-sticky cookies. Can also be ::COOKIE_EXPIRE or ::COOKIE_STICKY
	 * @param	string	Cookie path
	 * @param	string	Domain
	 */
	const COOKIE_EXPIRE = -1;
	const COOKIE_STICKY = -2;
	
	public static function cookie($name, $value, $timeout = 900, $path = '/', $domain = '')
	{
		// expire the cookie
		if ($timeout == self::COOKIE_EXPIRE)
		{
			setcookie($name, $value, time() - 1800, $path, $domain);
		}
		// set the cookie
		else
		{
			// it's sticky so keep it around for a while
			if ($timeout == self::COOKIE_STICKY)
			{
				$expire = time() + 60 * 60 * 24 * 365;
			}
			else
			{
				$expire = time() + $timeout;
			}
			
			setcookie($name, $value, $expire, $path, $domain);
		}
	}
	
	/**
	 * Alternate between two CSS classes
	 *
	 * @param	string	First CSS class name
	 * @param	string	Second CSS class name
	 */
	public static function swap_css_classes($class1 = 'alt1', $class2 = 'alt2')
	{
		static $count;
		return ($count++ % 2) ? $class1 : $class2;
	}
	
	/**
	 * Returns the 'source path' version of a file path. It adds a
	 * directory separator to the end of a string if it does not already
	 * exist.
	 *
	 * @param	string	Path
	 *
	 * @return	string	Path with directory separator ending
	 */
	public static function fetch_source_path($source)
	{
		if (substr($source, strlen($source) - 1) != DIRECTORY_SEPARATOR)
		{
			$source .= DIRECTORY_SEPARATOR;
		}
		return $source;
	}
	
	/**
	 * Force-download a file by sending application/octetstream
	 *
	 * @param	string	The text of the file to be streamed
	 * @param	string	File name of the new file
	 * @param	bool	Whether or not to die after stringeaming the file
	 */
	public static function download_file($file, $name, $exit = true)
	{
		header("Content-Type: application/octetstream");
		header("Content-Type: application/octet-stream");
		header('Expires: ' . gmdate('D, d M Y H:i:s') . ' GMT');
		header('Content-Disposition: attachment; filename="' . $name . '"');
		header('Content-length: ' . strlen($file));
		header('Cache-Control: must-revalidate, post-check=0, pre-check=0');
		header('Pragma: public');
		
		print($file);
		
		if ($exit)
		{
			exit;
		}
	}
	
	/**
	 * Verify that an email address is valid via regex
	 *
	 * @param	string	An email address
	 *
	 * @return	bool	Validity of the email address
	 */
	public static function is_valid_email($email)
	{
		return (preg_match('#^[a-z0-9\.\-\+_]+?@(.*?\.)*?[a-z0-9\-_]+?\.[a-z]{2,4}$#i', $email));
	}
	
	/**
	 * Generates a random string of random length (unless otherwise
	 * specified)
	 *
	 * @param	integer	Optional length
	 *
	 * @return	string	A random string
	 */
	public static function random($length = 0)
	{
		// length wasn't provided, so create our own
		if ($length < 1)
		{
			$length = rand(20, 65);
		}
		
		$string = '';
		while (strlen($string) < $length)
		{
			$type = rand(0, 300);
			if ($type < 100)
			{
				$string .= rand(0, 9);
			}
			else if ($type < 200)
			{
				$string .= chr(rand(65, 90));
			}
			else
			{
				$string .= chr(rand(97, 122));
			}
		}
		
		return $string;
	}
	
	/**
	 * Sets the current array position to be the specified key. This
	 * function should be avoided on large arrays.
	 *
	 * @param	array	The array whose counter is to be updated
	 * @param	mixed	The key of the element of the array that the counter is to be set to
	 *
	 * @return	mixed	Return the elelment of the array that we just put the counter to
	 */
	public static function array_set_current(&$array, $key)
	{
		reset($array);
		while (current($array) !== false)
		{
			if (key($array) == $key)
			{
				break;
			}
			next($array);
		}
		return current($array);
	}
	
	/**
	 * Calculates the microtime difference by taking a given microtime and
	 * subtracting it from the current one
	 *
	 * @param	string	The start microtime
	 *
	 * @return	float	Microtime difference
	 */
	public static function fetch_microtime_diff($mtstart)
	{
		$mtend = microtime();
		list($startMicro, $startSec) = explode(' ', $mtstart);
		list($endMicro, $endSec) = explode(' ', $mtend);
		return ($endMicro + $endSec) - ($startMicro + $startSec);
	}
	
	/**
	 * Fetches the extension of a file by extracting everything after the
	 * last period
	 *
	 * @param	string	Filename
	 *
	 * @return	string	The extension for the specifid file name
	 */
	public static function fetch_extension($filename)
	{
		$array = explode('.', $filename);
		
		if (sizeof($array) == 1)
		{
			return '';
		}
		
		return strval(end($array));
	}
	
	/**
	 * Gets the maximum file size for attachment uploading, as specified by
	 * PHP. If no value is present, 10 MB (represented in bytes) is
	 * returned.
	 *
	 * @return	integer	The maximum file upload size in bytes
	 */
	public static function fetch_max_php_file_size()
	{
		if ($size = @ini_get('upload_max_filesize'))
		{
			if (preg_match('#[^0-9].#', $size))
			{
				return $size;
			}
			else
			{
				return intval($size) * 1048576;
			}
		}
		else
		{
			return 10 * 1048576;
		}
	}
	
	/**
	 * Scans a specified directory path and returns an array of all the
	 * items in that directory. Directories found by this are end in a "/"
	 *
	 * @param	string	Path to scan
	 * @param	bool	Whether or not to recursively scan the directories encountered
	 * @param	bool	Ignore files beginning with a dot
	 *
	 * @return	array	A list of all the files in the specified path
	 */
	public static function scan_directory($path, $recurse = true, $ignoreDot = true)
	{
		return self::_help_scan_directory($path, $recurse, $ignoreDot, '');
	}
	
	/**
	 * Scans a specified directory path and returns an array of all the
	 * items in that directory. Directories found by this are end in a "/"
	 *
	 * @param	string	Path to scan
	 * @param	bool	Whether or not to recursively scan the directories encountered
	 * @param	bool	Ignore files beginning with a dot
	 * @param	string	Add to the beginning of the path
	 *
	 * @return	array	A list of all the files in the specified path
	 */
	private static function _help_scan_directory($path, $recurse = true, $ignoreDot = true, $pathAdd = '')
	{
		$filelist = array();
		$path = self::fetch_source_path($path);
		
		$dir = new DirectoryIterator($path);
		foreach ($dir as $file)
		{
			$name = $file->getFilename();
			if (($file->isDot() || $name[0] == '.') && $ignoreDot)
			{
				continue;
			}
			
			if ($file->isDir() && $recurse)
			{
				$filelist = array_merge($filelist, self::_help_scan_directory($path . $name, $recurse, $ignoreDot, $pathAdd . BSFunctions::fetch_source_path(str_replace($path, '', $file->getPathname()))));
				continue;
			}
			
			$filelist[] = $pathAdd . $name;
		}
		
		return $filelist;
	}
	
	/**
	 * Changes line breaks into one format
	 *
	 * @param	string	Text
	 * @param	string	New line break (default is UNIX \n format)
	 *
	 * @return	string	Text with one type of line break
	 */
	public static function convert_line_breaks($text, $convert_to = "\n")
	{
		$text = trim($text);
		$text = str_replace(array("\r\n", "\r", "\n"), "\n", $text);
		$text = str_replace("\n", $convert_to, $text);
		return $text;
	}
	
	/**
	 * Removes all empty() [by PHP's standards] elements in an array. This
	 * can be used in place of using PREG_SPLIT_NO_EMPTY.
	 *
	 * @param	array	An array to strip empties from
	 *
	 * @return	array	Full-valued array
	 */
	public static function array_strip_empty($array)
	{
		foreach ($array as $key => $value)
		{
			if (is_array($array["$key"]))
			{
				$array["$key"] = self::array_strip_empty($array["$key"]);
			}
			else if (empty($value) || is_null($value))
			{
				unset($array["$key"]);
			}
		}
		return $array;
	}
	
	/**
	 * 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
	 */
	public static function format_backtrace($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[] = 'Array';
					}
					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);
	}
	
	/**
	 * A variation of PHP's substr() method that takes in the start
	 * and end position of a string, rather than a start and length. This
	 * mimics Java's String.substring() method.
	 *
	 * @param	string	The string
	 * @param	integer	Start position
	 * @param	integer	End position
	 *
	 * @return	string	Part of a string
	 */
	public static function substring($string, $start, $end)
	{
		return substr($string, $start, $end - $start);
	}
	
	/**
	 * Converts a boolean value into the string 'Yes' or 'No'
	 *
	 * @param	boolean
	 * @return	string
	 */
	public static function bool_to_string($bool)
	{
		return ($bool ? _('Yes') : _('No'));
	}
}

?>