e107 class: refactoring, code formatting (standards), phpDoc - work in progress

class2.php

@@ -9,9 +9,9 @@
 * General purpose file
 *
 * $Source: /cvs_backup/e107_0.8/class2.php,v $
-* $Revision: 1.111 $
+* $Revision: 1.112 $
-* $Date: 2009-07-21 14:20:12 $
+* $Date: 2009-07-21 16:11:02 $
-* $Author: e107coders $
+* $Author: secretr $
 *
 */
 //
@@ -195,7 +195,7 @@ if(!isset($ADMIN_DIRECTORY))
 e107_require_once(realpath(dirname(__FILE__).'/'.$HANDLERS_DIRECTORY).'/e107_class.php');
 $e107_paths = compact('ADMIN_DIRECTORY', 'FILES_DIRECTORY', 'IMAGES_DIRECTORY', 'THEMES_DIRECTORY', 'PLUGINS_DIRECTORY', 'HANDLERS_DIRECTORY', 'LANGUAGES_DIRECTORY', 'HELP_DIRECTORY', 'DOWNLOADS_DIRECTORY');
 $e107 = e107::getInstance();
-$e107->_init($e107_paths, realpath(dirname(__FILE__)));
+$e107->init($e107_paths, realpath(dirname(__FILE__)));
 
 $inArray = array("'", ';', '/**/', '/UNION/', '/SELECT/', 'AS ');
 if (strpos($_SERVER['PHP_SELF'], 'trackback') === false)

e107_handlers/e107_class.php

@@ -1,26 +1,23 @@
 <?php
 /*
-+ ----------------------------------------------------------------------------+
+ * e107 website system
-|     e107 website system
+ *
-|
+ * Copyright (C) 2001-2008 e107 Inc (e107.org)
-|     Steve Dunstan 2001-2002
+ * Released under the terms and conditions of the
-|     http://e107.org
+ * GNU General Public License (http://www.gnu.org/licenses/gpl.txt)
-|     jalist@e107.org
+ *
-|
+ * e107 Main
-|     Released under the terms and conditions of the
+ *
-|     GNU General Public License (http://gnu.org).
+ * $Source: /cvs_backup/e107_0.8/e107_handlers/e107_class.php,v $
-|
+ * $Revision: 1.29 $
-|     $Source: /cvs_backup/e107_0.8/e107_handlers/e107_class.php,v $
+ * $Date: 2009-07-21 16:11:02 $
-|     $Revision: 1.28 $
+ * $Author: secretr $
-|     $Date: 2009-01-17 20:59:52 $
-|     $Author: e107steved $
-+----------------------------------------------------------------------------+
 */
 
 if (!defined('e107_INIT')) { exit; }
 
 /**
- * Core e107 class
+ * e107 class
  *
  */
 class e107
@@ -34,57 +31,224 @@ class e107
 	var $relative_base_path;
 	var $_ip_cache;
 	var $_host_name_cache;
+	
+	/**
+	 * Singleton instance
+	 * Allow class extends - override {@link getInstance()}
+	 * 
+	 * @var e107
+	 */
+	protected static $_instance = null;
+	
+	/**
+	 * e107 registry
+	 *
+	 * @var array
+	 */
+	private static $_registry = array();
+	
 	var $sql;
 	var $tp;
 	var $url;
 
+	
 	/**
-	 * e107 class constructor
+	 * Constructor
 	 * 
-	 * @param array $e107_paths
+	 * Use {@link getInstance()}, direct instantiating 
-	 * @param string $e107_root_path
+	 * is not possible for signleton objects
-	 * @return e107
+	 *
+	 * @return void
 	 */
-	function e107($php4_check)
+	protected function __construct()
 	{
-		if($php4_check !== 'e107_class_php4_very_long_hard_to_remember_check')
-		{
-			echo ('Fatal error! You are not allowed to direct instantinate an object for singleton class! Please use e107::getInstance()');
-			exit();
-		}
 	}
 
-	function _init($e107_paths, $e107_root_path)
+	/**
+	 * Cloning is not allowed
+	 *
+	 */
+	private function __clone()
+	{
+	}
+	
+	/**
+	 * Get singleton instance (php4 no more supported)
+	 *
+	 * @return e107
+	 */
+	public static function getInstance()
+	{
+		if(null == self::$_instance)
+		{
+		    self::$_instance = new self();
+		}
+	  	return self::$_instance;
+	}
+	
+	/**
+	 * Initialize environment path constants
+	 * Public proxy to the protected method {@link _init()}
+	 * 
+	 * @return e107
+	 */
+	public function init($e107_paths, $e107_root_path)
+	{
+		return $this->_init($e107_paths, $e107_root_path);
+	}
+	
+	/**
+	 * Resolve paths, will run only once
+	 * 
+	 * @return e107
+	 */
+	protected function _init($e107_paths, $e107_root_path)
+	{
+		if(empty($this->e107_dirs))
 		{
 			$this->e107_dirs = $e107_paths;
 			$this->set_paths();
 			$this->file_path = $this->fix_windows_paths($e107_root_path)."/";
 		}
+		return $this;
+	}
 	
 	/**
-	 * Get instance - php4 singleton implementation
+	 * Get data from the registry
+	 * Returns $default if data not found
+	 * Replacement of cachevar()
 	 * 
-	 * @return singleton object
+	 * @param string $id 
+	 * @return mixed
 	 */
-	function &getInstance()
+	public static function getRegistry($id, $default = null)
 	{
-		static $instance = array();//it's array because of an odd PHP 4 bug
+		if(isset(self::$_registry[$id]))
-
-		if(!$instance)
 		{
-		    $instance[0] = new e107('e107_class_php4_very_long_hard_to_remember_check');
+			return self::$_registry[$id];
-		}
-	  	return $instance[0];
 		}
 		
-	function set_base_path()
+		return $default;
+	}
+	
+	/**
+	 * Add data to the registry - replacement of getcachedvars().
+	 * $id is path-like unique id bind to the passed data.
+	 * If $data argument is null, $id will be removed from the registry.
+	 * When removing objects from the registry, __destruct() method will be auto-executed 
+	 * if available
+	 * 
+	 * Naming standards (namespaces):
+	 * 'area/area_id/storage_type'<br>
+	 * where <br>
+	 * - area = 'core'|'plugin'|'external' (everything else)
+	 * - area_id = core handler id|plugin name (depends on area)
+	 * - (optional) storage_type = current data storage stack
+	 * 
+	 * Examples:
+	 * - 'core/e107/' - reserved for this class
+	 * - 'core/e107/singleton/' - singleton objects repo {@link getSingleton()}
+	 * 
+	 * @param string $id
+	 * @param mixed|null $data
+	 * @return void
+	 */
+	public static function setRegistry($id, $data = null, $allow_override = true)
+	{
+		if(null === $data)
+		{
+			if(is_object(self::$_registry[$id]) && method_exists(self::$_registry[$id], '__destruct'))
+			{
+				self::$_registry[$id]->__destruct();
+			}
+			unset(self::$_registry[$id]);
+			return;
+		}
+		
+		if(!$allow_override && null !== self::getRegistry($id))
+		{
+			return;
+		}
+		
+		self::$_registry[$id] = $data;
+	}
+	
+	/**
+	 * Retrieve singleton object
+	 *
+	 * @param string $class_name
+	 * @param string $path optional script path
+	 * @return Object
+	 */
+	public static function getSingleton($class_name, $path = null)
+	{
+		$id = 'core/e107/singleton/'.$class_name;
+		if(!e107::getRegistry($id))
+		{
+			if(null !== $path)
+			{
+				require_once($path); //no existence/security checks here!
+			}
+			if(class_exists($class_name))
+			{
+				e107::setRegistry($id, new $class_name());
+			}
+		}
+
+		return self::getRegistry($id);
+	}
+	
+	/**
+	 * Retrieve object
+	 * We prepare for __autoload
+	 *
+	 * @param string $class_name
+	 * @param mxed $arguments
+	 * @param string $path optional script path
+	 * @return object|null
+	 */
+	public static function getObject($class_name, $arguments = null, $path = null)
+	{
+		if(null !== $path)
+		{
+			require_once($path); //no existence/security checks here!
+		}
+		if(class_exists($class_name))
+		{
+			if(null !== $arguments) return $class_name($arguments);
+			return $class_name();
+		}
+
+		//trigger_error("Class {$class_name} not found!", E_USER_ERROR);
+		return null;
+	}
+	
+	/**
+	 * Retrieve text parser singleton object
+	 *
+	 * @return e_parse
+	 */
+	public static function getParser()
+	{
+		return self::getSingleton('e_parse', e_HANDLER.'e_parse_class.php');
+	}
+
+	/**
+	 * @return e107
+	 */
+	public function set_base_path()
 	{
 		global $pref;
 		$this->base_path = ($pref['ssl_enabled'] == 1 ?  $this->https_path : $this->http_path);
+		return $this;
 	}
 
 
-	function set_paths()
+	/**
+	 * Set all environment vars and constants
+	 *
+	 */
+	public function set_paths()
 	{
 		global $DOWNLOADS_DIRECTORY, $ADMIN_DIRECTORY, $IMAGES_DIRECTORY, $THEMES_DIRECTORY, $PLUGINS_DIRECTORY,
 		$FILES_DIRECTORY, $HANDLERS_DIRECTORY, $LANGUAGES_DIRECTORY, $HELP_DIRECTORY, $CACHE_DIRECTORY,
@@ -218,6 +382,12 @@ class e107
 		}
 	}
 
+	/**
+	 * Fix Windows server path
+	 *
+	 * @param string $path resolved server path
+	 * @return string fixed path
+	 */
 	function fix_windows_paths($path)
 	{
 		$fixed_path = str_replace(array('\\\\', '\\'), array('/', '/'), $path);
@@ -228,10 +398,12 @@ class e107
 	/**
 	 * Check if current user is banned
 	 * 
+	 * XXX add more description? return type e107?
+	 * @return void
 	 */
-	function ban()
+	public function ban()
 	{
-		global $sql, $e107, $tp, $pref;
+		global $sql, $pref;
 		$ban_count = $sql->db_Count("banlist");
 		if($ban_count)
 		{
@@ -253,10 +425,9 @@ class e107
 					$vals[] = substr($ip, 0, -14).'*';
 				}
 			}
-
 			if(varsettrue($pref['enable_rdns']))
 			{
-		  $tmp = array_reverse(explode('.',$addr = $e107->get_host_name(getenv('REMOTE_ADDR'))));
+				$tmp = array_reverse(explode('.', $this->get_host_name(getenv('REMOTE_ADDR'))));
 				$line = '';
 				//		  $vals[] = $addr;
 				foreach($tmp as $e)
@@ -265,12 +436,10 @@ class e107
 					$vals[] = '*'.$line;
 				}
 			}
-
 			if((defined('USEREMAIL')&&USEREMAIL))
 			{
 				$vals[] = USEREMAIL;
 			}
-
 			if(($ip!='127.0.0.1')&&count($vals))
 			{
 				$match = "`banlist_ip`='".implode("' OR `banlist_ip`='", $vals)."'";
@@ -279,14 +448,20 @@ class e107
 		}
 	}
 
-
+	/**
-	// Check the banlist table. $query is used to determine the match.
+	 * Check the banlist table. $query is used to determine the match.
-	// If $show_error, displays "HTTP/1.1 403 Forbidden"
+	 * If $do_return, will always return with ban status - TRUE for OK, FALSE for banned.
-	// If $do_return, will always return with ban status - TRUE for OK, FALSE for banned.
+	 * If return permitted, will never display a message for a banned user; otherwise will display any message then exit
-	// If return permitted, will never display a message for a banned user; otherwise will display any message then exit
+	 * XXX - clean up
-	function check_ban($query,$show_error=TRUE, $do_return = FALSE)
+	 * 
+	 * @param string $query
+	 * @param boolean $show_error
+	 * @param boolean $do_return
+	 * @return boolean
+	 */
+	public function check_ban($query, $show_error = TRUE, $do_return = FALSE)
 	{
-		global $sql, $tp, $pref, $admin_log, $e107;
+		global $sql, $tp, $pref, $admin_log;
 		//$admin_log->e_log_event(4,__FILE__."|".__FUNCTION__."@".__LINE__,"DBG","Check for Ban",$query,FALSE,LOG_TO_ROLLING);
 		if($sql->db_Select('banlist', '*', $query.' ORDER BY `banlist_bantype` DESC'))
 		{
@@ -298,27 +473,25 @@ class e107
 				//$admin_log->e_log_event(4,__FILE__."|".__FUNCTION__."@".__LINE__,"DBG","Whitelist hit",$query,FALSE,LOG_TO_ROLLING);
 				return TRUE;
 			}
-	
 			// Found banlist entry in table here
 			if(($row['banlist_banexpires']>0)&&($row['banlist_banexpires']<time()))
 			{ // Ban has expired - delete from DB
 				$sql->db_Delete('banlist', $query);
 				return TRUE;
 			}
-	
 			if(varsettrue($pref['ban_retrigger'])&&varsettrue($pref['ban_durations'][$row['banlist_bantype']]))
 			{ // May need to retrigger ban period
-				$sql->db_Update('banlist',
+				$sql->db_Update('banlist', "`banlist_banexpires`=".intval(time()+($pref['ban_durations'][$row['banlist_bantype']]*60*60)), "WHERE `banlist_ip`='{$row['banlist_ip']}'");
-					"`banlist_banexpires`=".intval(time() + ($pref['ban_durations'][$row['banlist_bantype']]*60*60)),
-					"WHERE `banlist_ip`='{$row['banlist_ip']}'");
 				//$admin_log->e_log_event(4,__FILE__."|".__FUNCTION__."@".__LINE__,"DBG","Retrigger Ban",$row['banlist_ip'],FALSE,LOG_TO_ROLLING);
 			}
 			//$admin_log->e_log_event(4,__FILE__."|".__FUNCTION__."@".__LINE__,"DBG","Active Ban",$query,FALSE,LOG_TO_ROLLING);
-			if ($show_error) header("HTTP/1.1 403 Forbidden", true);
+			if($show_error)
+				header("HTTP/1.1 403 Forbidden", true);
 			if(isset($pref['ban_messages']))
 			{ // May want to display a message
 				// Ban still current here
-				if ($do_return) return FALSE;
+				if($do_return)
+					return FALSE;
 				echo $tp->toHTML(varsettrue($pref['ban_messages'][$row['banlist_bantype']])); // Show message if one set
 			}
 			$admin_log->e_log_event(4, __FILE__."|".__FUNCTION__."@".__LINE__, 'BAN_03', 'LAN_AUDIT_LOG_003', $query, FALSE, LOG_TO_ROLLING);
@@ -328,17 +501,36 @@ class e107
 		return TRUE; // Email address OK
 	}
 
-
+	/**
-	// Add an entry to the banlist. $bantype = 1 for manual, 2 for flooding, 4 for multiple logins
+	 * Add an entry to the banlist. $bantype = 1 for manual, 2 for flooding, 4 for multiple logins
-	// Returns TRUE if ban accepted.
+	 * Returns TRUE if ban accepted.
-	// Returns FALSE if ban not accepted (i.e. because on whitelist, or invalid IP specified)
+	 * Returns FALSE if ban not accepted (i.e. because on whitelist, or invalid IP specified)
-	function add_ban($bantype,$ban_message='',$ban_ip='',$ban_user = 0,$ban_notes='')
+	 * FIXME - remove $admin_log global, add admin_log method getter instead
+	 * 
+	 * @param string $bantype
+	 * @param string $ban_message
+	 * @param string $ban_ip
+	 * @param integer $ban_user
+	 * @param string $ban_notes
+	 * 
+	 * @return boolean check result
+	 */
+	public function add_ban($bantype, $ban_message = '', $ban_ip = '', $ban_user = 0, $ban_notes = '')
 	{
-	  global $sql, $pref, $e107;
+		global $sql, $pref, $e107, $admin_log;
-	  if (!$ban_message) $ban_message = 'No explanation given';
+		if(!$ban_message)
-	  if (!$ban_ip) $ban_ip = $this->getip();
+		{
-	  $ban_ip = preg_replace("/[^\w@\.]*/",'',urldecode($ban_ip));		// Make sure no special characters
+			$ban_message = 'No explanation given';
-	  if (!$ban_ip) return FALSE;
+		}
+		if(!$ban_ip)
+		{
+			$ban_ip = $this->getip();
+		}
+		$ban_ip = preg_replace('/[^\w@\.]*/', '', urldecode($ban_ip)); // Make sure no special characters
+		if(!$ban_ip)
+		{
+			return FALSE;
+		}
 		// See if the address is in the whitelist
 		if($sql->db_Select('banlist', '*', '`banlist_bantype` >= '.BAN_TYPE_WHITELIST))
 		{ // Got a whitelist entry for this
@@ -350,36 +542,35 @@ class e107
 			$ban_message .= 'Host: '.$e107->get_host_name($ban_ip);
 		}
 		// Add using an array - handles DB changes better
-	  $sql->db_Insert('banlist',array('banlist_ip' => $ban_ip, 'banlist_bantype' => $bantype, 'banlist_datestamp' => time(),
+		$sql->db_Insert('banlist', array('banlist_ip' => $ban_ip , 'banlist_bantype' => $bantype , 'banlist_datestamp' => time() , 'banlist_banexpires' => (varsettrue($pref['ban_durations'][$bantype]) ? time()+($pref['ban_durations'][$bantype]*60*60) : 0) , 'banlist_admin' => $ban_user , 'banlist_reason' => $ban_message , 'banlist_notes' => $ban_notes));
-		'banlist_banexpires' => (varsettrue($pref['ban_durations'][$bantype]) ? time() + ($pref['ban_durations'][$bantype]*60*60) : 0),
-		'banlist_admin' => $ban_user, 'banlist_reason' => $ban_message, 'banlist_notes' => $ban_notes));
 		return TRUE;
 	}
 
-
 	/**
 	 * Get the current user's IP address
+	 * returns the address in internal 'normalised' IPV6 format - so most code should continue to work provided the DB Field is big enougn
 	 * 
 	 * @return string
-	 * returns the address in internal 'normalised' IPV6 format - so most code should continue to work provided the DB Field is big enougn
 	 */
-	function getip()
+	public function getip()
 	{
 		if(!$this->_ip_cache)
 		{
 			if(getenv('HTTP_X_FORWARDED_FOR'))
 			{
 				$ip = $_SERVER['REMOTE_ADDR'];
-				if (preg_match("/^([0-9]+\.[0-9]+\.[0-9]+\.[0-9]+)/", getenv('HTTP_X_FORWARDED_FOR'), $ip3))
+				$ip3 = array();
+				if(preg_match('/^([0-9]+\.[0-9]+\.[0-9]+\.[0-9]+)/', getenv('HTTP_X_FORWARDED_FOR'), $ip3))
 				{
-					$ip2 = array('#^0\..*#',
+					$ip2 = array(
-						'#^127\..*#', 							// Local loopbacks
+						'#^0\..*#' , '#^127\..*#' , // Local loopbacks
 						'#^192\.168\..*#' , // RFC1918 - Private Network
 						'#^172\.(?:1[6789]|2\d|3[01])\..*#' , // RFC1918 - Private network
 						'#^10\..*#' , // RFC1918 - Private Network
 						'#^169\.254\..*#' , // RFC3330 - Link-local, auto-DHCP
-						'#^2(?:2[456789]|[345][0-9])\..*#'		// Single check for Class D and Class E
+						'#^2(?:2[456789]|[345][0-9])\..*#'
-						);
+					); // Single check for Class D and Class E
+					
 					$ip = preg_replace($ip2, $ip, $ip3[1]);
 				}
 			}
@@ -396,11 +587,15 @@ class e107
 		return $this->_ip_cache;
 	}
 
-
+	/**
-
+	 * Encode an IP address to internal representation. Returns string if successful; FALSE on error
-	// Encode an IP address to internal representation. Returns string if successful; FALSE on error
+	 * Default separates fields with ':'; set $div='' to produce a 32-char packed hex string
-	// Default separates fields with ':'; set $div='' to produce a 32-char packed hex string
+	 * 
-	function ipEncode($ip, $div=':')
+	 * @param string $ip
+	 * @param string $div divider
+	 * @return string encoded IP
+	 */
+	public function ipEncode($ip, $div = ':')
 	{
 		$ret = '';
 		$divider = '';
@@ -444,11 +639,17 @@ class e107
 		return FALSE; // Unknown
 	}
 
-
+	/**
-	// Takes an encoded IP address - returns a displayable one
+	 * Takes an encoded IP address - returns a displayable one
-	// Set $IP4Legacy TRUE to display 'old' (IPv4) addresses in the familiar dotted format, FALSE to display in standard IPV6 format
+	 * Set $IP4Legacy TRUE to display 'old' (IPv4) addresses in the familiar dotted format, 
-	// Should handle most things that can be thrown at it.
+	 * FALSE to display in standard IPV6 format
-	function ipDecode($ip, $IP4Legacy = TRUE)
+	 * Should handle most things that can be thrown at it.
+	 *
+	 * @param string $ip encoded IP
+	 * @param boolean $IP4Legacy
+	 * @return string decoded IP
+	 */
+	public function ipDecode($ip, $IP4Legacy = TRUE)
 	{
 		if (strstr($ip,'.'))
 		{
@@ -508,9 +709,13 @@ class e107
 		return $ret;
 	}
 	
-
+	/**
-	// Given a string which may be IP address, email address etc, tries to work out what it is
+	 * Given a string which may be IP address, email address etc, tries to work out what it is
-	function whatIsThis($string)
+	 *
+	 * @param string $string
+	 * @return string ip|email|url|ftp|unknown
+	 */
+	public function whatIsThis($string)
 	{
 		if (strstr($string,'@')) return 'email';		// Email address
 		if (strstr($string,'http://')) return 'url';
@@ -523,7 +728,13 @@ class e107
 		return 'unknown';
 	}
 
-	function get_host_name($ip_address)
+	/**
+	 * Retrieve & cache host name
+	 *
+	 * @param string $ip_address
+	 * @return string host name
+	 */
+	public function get_host_name($ip_address)
 	{
 		if(!$this->_host_name_cache[$ip_address])
 		{
@@ -532,10 +743,24 @@ class e107
 		return $this->_host_name_cache[$ip_address];
 	}
 
-
+	/**
-	// Return a memory value formatted helpfully
+	 * Return a memory value formatted helpfully
-	// $dp overrides the number of decimal places displayed - realistically, only 0..3 are sensible
+	 * $dp overrides the number of decimal places displayed - realistically, only 0..3 are sensible
-	function parseMemorySize($size, $dp = 2)
+	 * FIXME e107->parseMemorySize() START
+	 * - maybe we are in need of General Helper handler, this + the above ban/ip related methods 
+	 * are not fitting e107 class logic anymore
+	 * - change access to public static - more useful 
+	 * - out of (integer) range case? 
+	 * 32 bit systems range: -2147483648 to 2147483647
+	 * 64 bit systems range: -9223372036854775808 9223372036854775807
+	 * {@link http://www.php.net/intval}
+	 * FIXME e107->parseMemorySize() END
+	 *
+	 * @param integer $size
+	 * @param integer $dp
+	 * @return string formatted size
+	 */
+	public function parseMemorySize($size, $dp = 2)
 	{
 		if (!$size) { $size = 0; }
 		if ($size < 4096)
@@ -567,22 +792,27 @@ class e107
 
 	/**
 	 * Get the current memory usage of the code
+	 * If $separator argument is null, raw data (array) will be returned
 	 * 
-	 * @return string memory usage
+	 * @param null|string $separator
+	 * @return string|array memory usage
 	 */
-	function get_memory_usage()
+	public function get_memory_usage($separator = '/')
 	{
+		$ret = array();
 		if(function_exists("memory_get_usage"))
 		{
-	      $ret = $this->parseMemorySize(memory_get_usage());
+	      $ret[] = $this->parseMemorySize(memory_get_usage());
 		  // With PHP>=5.2.0, can show peak usage as well
-	      if (function_exists("memory_get_peak_usage")) $ret .= '/'.$this->parseMemorySize(memory_get_peak_usage(TRUE));
+	      if (function_exists("memory_get_peak_usage")) $ret[] = $this->parseMemorySize(memory_get_peak_usage(TRUE));
 		  return $ret;
 		}
 		else
 		{
-		  return ('Unknown');
+		  $ret[] = 'Unknown';
 		}
+		
+		return (null !== $separator ? implode($separator, $ret) : $ret);
 	}
 
 }