/lib/session/cfSession.class.php

<?php
/**
 -----------------------------------------------------------------------------
* SESSION MANAGEMENT (singleton)
*
* This class is managing the standard PHP session. (start, read & write)
* For each application you can define a seperate session part, so you can minimize the risk,
* that outher application working with this framwork catch your data.
*
* Also you are able to define the session name (e.g.: PHPSESSID) in your application config.
* All session variables can be accessed as if they were class members.*
*
 -----------------------------------------------------------------------------
 -----------------------------------------------------------------------------
* @copyright (C) 2011 Cyberfox Software Solutions e.U.
* @license http://www.gnu.org/licenses/lgpl.html GNU Lesser General Public License version 3 (LGPLv3) 
* @author Christian Graf <christian.graf@cyberfox.at>
 -----------------------------------------------------------------------------
 -----------------------------------------------------------------------------
* @package redfox
* @subpackage dataset
* @category data
 -----------------------------------------------------------------------------
 -----------------------------------------------------------------------------
* @version	$Id: cfSession.class.php 86 2012-05-08 08:13:17Z cgraf $
* @date	$Date: 2012-05-08 10:13:17 +0200 (Di, 08 Mai 2012) $
* @svnauthor	$Author: cgraf $
 -----------------------------------------------------------------------------
*/

class cfSession
{
	/**
	 * The current instance of this class.
	 *
	 * @var cfSession
	 * @access private
	 * @static
	 */
	private static $instance = null;
	
	/**
	 * The defined session name.
	 * Default to "PHPSESSID"
	 *
	 * @var string
	 * @access private
	 * @static
	 */
	private static $sessionname = null;
	
	/**
	 * The current active session id.
	 *
	 * @var string
	 * @access private
	 * @static
	 */
	private static $session_id = null;
	
	/**
	 * The current active application name to differ the session data.
	 *
	 * @var string
	 * @access private
	 * @static
	 */
	private static $applicationname = null;
	
	
	/**
	 * Constructor
	 *
	 * Check the config for session settings and set the properties.
	 * If no settings available, default settings will be set.
	 *
	 * @return void
	 * @access private
	 * @final
	 */
	final private function __construct()
	{
		if(is_null(self::$sessionname))
		{
			$name = cfConfig::GetEntry('name', 'session');
			if(empty($name)) $name = 'PHPSESSID'; //default
			self::$sessionname = $name;
		}
		
		if(is_null(self::$session_id))
		{
			self::$session_id = session_id();
		}
	}
	
	/**
	 * getName()
	 *
	 * Get the current defined session name.
	 *
	 * @return string The current defined session name
	 * @access public
	 * @static
	 * @final
	 */
	final public static function GetName()
	{
		if(is_null(self::$sessionname))
		{
			$name = cfConfig::GetEntry('name', 'session');
			if(empty($name)) $name = 'PHPSESSID'; //default
			self::$sessionname = $name;
		}
		
		return self::$sessionname;
	}
	
	/**
	 * getId()
	 *
	 * Get the current active session id.
	 *
	 * @return string The current active session id
	 * @access public
	 * @static
	 * @final
	 */
	final public static function GetId()
	{
		if(is_null(self::$session_id))
		{
			self::$session_id = session_id();
		}
		
		return self::$session_id;
	}
	
	/**
	 * getInstance()
	 *
	 * Returns a reference to the singleton instance of this class.
	 *
	 * @return cfSession Reference to the singelton instance of this class
	 * @access public
	 * @static
	 * @final
	 */
	final public static function &GetInstance()
	{
		if(!isset(self::$instance) || is_null(self::$instance) || !is_object(self::$instance))
		{
			self::$instance = new cfSession();
		}
		
		return self::$instance;
	}
	
	/**
	 * getIdentifier()
	 *
	 * Get the current active identifier to differ the session data.
	 *
	 * If no application_key defined in the config, CFSESSION will be returned as identifier.
	 *
	 * @return string The current active identifier
	 * @access public
	 * @static
	 * @final
	 */
	final public static function GetIdentifier()
	{
		if(is_null(self::$applicationname))
		{
			$key = cfConfig::GetEntry('application_key', 'application');
			if(empty($key)) $key = 'CFSESSION'; //default
			self::$applicationname = $key;
		}
		
		return self::$applicationname;
	}
	
	/**
	 * start()
	 *
	 * Start the PHP Session.
	 *
	 * Must be called before you wish to work with.
	 *
	 * @param bool $CheckSettings If TRUE, the settings will refreshed automaticly
	 * @return void
	 * @access public
	 * @static
	 * @final
	 */
	final public static function Start($CheckSettings=true)
	{
		$sessionName = self::GetName();
		if(!empty($sessionName))
		{
			session_name($sessionName);
		}
		
		if(session_id() == '')
		{
			if($CheckSettings === true)
			{
				$settings = array( //Default values defined in php.ini - state of settings = PHP Version 5.3.1
					'session.auto_start' => 'auto_start',
					'session.bug_compat_42' => 'bug_compat_42',
					'session.bug_compat_warn' => 'bug_compat_warn',
					'session.cache_expire' => 'cache_expire',
					'session.cache_limiter' => 'cache_limiter',
					'session.cookie_domain' => 'cookie_domain',
					'session.cookie_httponly' => 'cookie_httponly',
					'session.cookie_lifetime' => 'cookie_lifetime',
					'session.cookie_path' => 'cookie_path',
					'session.cookie_secure' => 'cookie_secure',
					'session.entropy_file' => 'entropy_file',
					'session.entropy_length' => 'entropy_length',
					'session.gc_divisor' => 'gc_divisor',
					'session.gc_maxlifetime' => 'gc_maxlifetime',
					'session.gc_probability' => 'gc_probability',
					'session.hash_bits_per_character' => 'hash_bits_per_character',
					'session.hash_function' => 'hash_function',
					'session.name' => 'name',
					'session.referer_check' => 'referer_check',
					'session.save_handler' => 'save_handler',
					'session.save_path' => 'save_path',
					'session.serialize_handler' => 'serialize_handler',
					'session.use_cookies' => 'use_cookies',
					'session.use_only_cookies' => 'use_only_cookies',
					'session.use_trans_sid' => 'use_trans_sid'
				);
				foreach($settings as $iniSetting => $configName)
				{
					$tmp = cfConfig::GetEntry($configName, 'session');
					if(!is_null($tmp))
					{
						ini_set($iniSetting, $tmp);
					}
				}
			}
			session_start();
		}
		
		$ident = self::GetIdentifier();
		if(!isset($_SESSION[$ident]))
			$_SESSION[$ident] = array();
		
		if(!isset($_SESSION[$ident]['_timeout']))
			$_SESSION[$ident]['_timeout'] = intval(time() + self::GetLifetime());
	}
	
	/**
	 * Destroy the current session and unset all session stored variables.
	 *
	 * @return void
	 * @access:public
	 * @final
	 * @static
	 */
	final public static function End()
	{
		session_unset();
		session_destroy();
	}
	
	/**
	 * getEntry()
	 *
	 * Get an variable stored in the session.
	 *
	 * @param string $Name The name of the designated session variable
	 * @return mixed The value of your designated session varibale
	 * @access public
	 * @static
	 * @final
	 */
	final public static function GetEntry($Name)
	{
		$ident = self::GetIdentifier();

		if(isset($_SESSION[$ident][$Name]))
			return $_SESSION[$ident][$Name];
		else
			return null;
	}
	
	/**
	 * __get() - PHP Magic Function
	 *
	 * Allows to get session variables directly via the $obj->varname syntax.
	 *
	 * @param string $Name The name of the designated session variable
	 * @return mixed The value of your designated session varibale
	 * @access public
	 * @final
	 */
	final public function __get($Name)
	{
		return self::GetEntry($Name);
	}
	
	/**
	 * __isset() - PHP Magic Function
	 *
	 * Allows to use isset($obj->varname)
	 *
	 * @param string $Name The name of the designated session variable
	 * @return bool TRUE if the designated variable has been set.
	 * @access public
	 * @final
	 */
	final public function __isset($Name)
	{
		$ident = self::GetIdentifier();
		return isset($_SESSION[$ident][$Name]);
	}
	
	/**
	 * setEntry()
	 *
	 * Set/Store an variable into the the session.
	 *
	 * @param string $Name The name of the designated session variable you wish to set
	 * @param mixed $Value The value the designated session variable
	 * @return void
	 * @access public
	 * @static
	 * @final
	 */
	final public static function SetEntry($Name, $Value)
	{
		$ident = self::GetIdentifier();
		
		if(!isset($_SESSION[$ident]))
			$_SESSION[$ident] = array();
		$_SESSION[$ident][$Name] = $Value;
		
		if($Name != '_timeout')
			$_SESSION[$ident]['_timeout'] = intval(time() + self::GetLifetime());
	}
	
	/**
	 * __set() - PHP Magic Function
	 *
	 * Allows to set session variables directly via the $obj->varname syntax.
	 *
	 * @param string $Name The name of the designated session variable you wish to set
	 * @param mixed $Value The value the designated session variable
	 * @return void
	 * @access public
	 * @final
	 */
	final public function __set($Name, $Value)
	{
		self::SetEntry($Name, $Value);
	}
	
/**
	 * unsetEntry()
	 *
	 * Unset/Selete a variable from the the session.
	 *
	 * @param string $Name The name of the designated session variable you wish to set
	 * @return void
	 * @access public
	 * @static
	 * @final
	 */
	final public static function UnsetEntry($Name)
	{
		$ident = self::GetIdentifier();
		
		if(isset($_SESSION[$ident][$Name]))
		{
			$_SESSION[$ident][$Name] = null;
			unset($_SESSION[$ident][$Name]);
			
			if($Name != '_timeout')
				$_SESSION[$ident]['_timeout'] = intval(time() + self::GetLifetime());
		}
	}
	
	/**
	 * __unset() - PHP Magic Function
	 *
	 * Allows to directly unset via the unset($obj->fieldname) syntax.
	 *
	 * @param string $Name The name of the designated session variable you wish to unset
	 * @return void
	 * @access public
	 * @final
	 */
	final public function __unset($Name)
	{
		self::UnsetEntry($Name);
	}
	
	/**
	 * dump()
	 *
	 * Dumps the complete session array direclty on screen.
	 *
	 * @return void
	 * @access public
	 */
	public function dump($IdentOnly = false)
	{
		$data = $_SESSION;
		if($IdentOnly === true)
		{
			$ident = self::GetIdentifier();
			if(isset($_SESSION[$ident]))
			{
				$data = $_SESSION[$ident];
			}
		}
			
		if(php_sapi_name() == 'cli')
		{ //for command line output
			echo "\n" .print_r($data, true) ."\n";
		}
		else
		{ //for html output
			echo '<pre>' .print_r($data, true) .'</pre>';
		}
	}
	
	/**
	 * Get the designated session lifetime in seconds.
	 *
	 * The lifetime can be defined in the session.php config file. Defaults to 1440 seconds (=24 minutes)
	 *
	 * @return int The current session lifetime in seconds
	 * @access public
	 * @static
	 */
	public static function GetLifetime()
	{
		$maxLifetime = cfConfig::GetEntry('gc_maxlifetime', 'session');
		if(empty($maxLifetime))
			$maxLifetime = 1440; //default php session lifetime of 24 minutes
		return intval($maxLifetime);
	}
	
	/**
	 * Check if the current session is valid.
	 * If the lifetime has not been expired, the lifetime will be renew
	 *
	 * @return bool TRUE if the session lifetime has not been expired
	 * @access public
	 * @static
	 */
	public static function CheckLifetime()
	{
		$session = self::GetInstance();
		if(isset($session->_timeout) && intval($session->_timeout) > time())
		{
			$ident = self::GetIdentifier();
			$_SESSION[$ident]['_timeout'] = intval(time() + self::GetLifetime());
			return true;
		}
		else
			return false;
	}
	
	/**
	 * Destroy the current session and free all session variables.
	 *
	 * @return void
	 * @access public
	 * @static
	 */
	public static function Destroy()
	{
		session_unset();
		session_destroy();
	}
	
	/**
	 * Clenup the current session. => Free all session variables.
	 *
	 * @return void
	 * @access public
	 * @static
	 */
	public static function Cleanup()
	{
		session_unset();
	}
}

?>