<?php 
/* vim: set noexpandtab shiftwidth=4 tabstop=4 foldmethod=marker: */

# Instances of this class operate in two different modes, depending on
# whether or not a PHP session is already in progress
# (is_array($_SESSION)).  If a session has been previously started,
# class methods are limited to registering and unregistering variables
# and retrieving information about the previously started session.   
#
# Other classes may also initiate a session, or a session may be
# auto-started if session.auto_start is turned on, and it would be
# inappropriate for a session class to modify these settings outside
# of other classes, such as the PEAR Auth class, which also depend on
# session continuity.  Setup of a session management profile should be
# done before instantiation of any class, including this one, which
# establishes a session.
#
# This class is intended purely as a programming aid to assist in the
# objectification of session data and session-related methods and as a
# storage location for session information.  Class methods follow
# those in PHPlib's session class inasmuch as possible, however full
# emulation of PHPlib's session class is not possible in current
# versions of PHP, nor are methods supported in this class which might
# conflict with other session related methods or mechanisms internal
# to other classes.
#
# The code herein is covered under the terms of the GNU General Public
# License, Version 3, a copy of which can be found at
# <http://www.gnu.org/licenses/gpl-3.0.txt>.
#
# This class requires PHP5 or greater
/*
 * COOKIE vs. GET
 *
 * Columns:  session.u_c    = session.use_cookies
 *           session.u_o_c  = session.use_only_cookies
 *           session.u_t_s  = session.use_trans_sid
 *
 * Results:  C = session set by cookie
 *           U = session set in URL
 *           B = session not set - broken!
 *
 * SERVER                                     | BROWSER RESULT
 * session.u_c	session.u_o_c	session.u_t_s	cook_on	cook_off
 * -------------------------------------------------------------
 * true			true			false			C		B			Default setting for max security		CC
 * true			true			true			U->C	B			Uses URL until cookie estab.
 * false		true			false			B		B			
 * false		true			true			U		B
 * true			false			false			C		B
 * true			false			true			U->C	U			Uses URL until cookie estab.			CU
 * false		false			false			B		B			Cookie set if allowed, sess broken
 * false		false			true			U		U													UU, UC
 *
 */

# 
# Publicly accessible methods
# ---------------------------
#
# fmplib_session::__construct()
#
# Synopsis:
#
# Description:
#
#   Class constructor.  Initializes instance variables, 
#
#
# fmplib_session::__destruct()
#
# Synopsis:
#
# Description:
#
#   Class destructor.  Freezes all registered variables
#
#
# fmplib_session::name()
#
# Synopsis:
#
#   string = name()
#
# Description:
#
#   Returns the session name as currently registered with the PHP
#   session.
#
#
# fmplib_session::new_id()
#
# Synopsis:
#
#   bool new_id()
#
# Description:
#
#   If a dominant session has been instantiated, replaces the current
#   session id with a new one, and deletes the current session
#   information.  If the session is not dominant, does nothing and
#   returns false.
#
#
# fmplib_session::get_id()
#
# Synopsis:
#
#   string get_id()
#
# Description:
#
#   Returns the current session ID, as registered with the current
#   fmplib_session object.
#
#
# fmplib_session::register()
#
# Synopsis:
# 
#   void register(mixed $varnames)
#
# Description:
#   
#   Registers variables identified by $varnames with the current
#   session under $_SESSION["fmplib"]["data"].  $varnames may be a
#   comma separated string or an array list of names, represented as
#   strings, e.g. "foo" or "foo,bar,baz" or {"foo","bar","baz"}.
#   Registered variables become persistent.
#   
#
# fmplib_session::unregister()
#
# Synopsis:
#
#   bool unregister(mixed $varnames)
#
# Description:
#
#   Unregisters variables identified by $varnames from the current
#   session under $_SESSION["fmplib"]["data"].  $varnames may be a
#   comma separated string or an array list of names, represented as
#   strings, e.g. "foo" or "foo,bar,baz" or {"foo","bar","baz"}.
#   Unregistered variables are no longer persistent.  Always returns
#   true.
#
#
# fmplib_session::put_id()
#
# Synopsis:
#
#   bool put_id()
#
# Description:
#  
#   If and only if this instance is attached to a dominant session,
#   delete the cookie holding the session id.  Return true if the
#   session is dominant and uses cookies and cookie can be deleted.
#   Otherwise return false.
#   
#
# fmplib_session::delete()
#
# Synopsis:
#
#   bool delete()
#
# Description:
#
#   If the instance of this class is attached to a dominant session,
#   destroy the session by calling session_destroy().  In any case,
#   $_SESSION["fmplib"] is unset.
#
#
# fmplib_session::url()
#
# Synopsis:
#
#   string url(string $url)
#
# Description:
#
#   If using URL-based session data, return $url with the session data
#   appended, otherwise just return $url unaltered.
#
#
# fmplib_session::purl()
#
# Synopsis:
#
#   void purl($url)
#
# Description:
#
#   print $url.  See fmplib_session::url() above.
#
#
# fmplib_session::self_url()
#
# Synopsis:
#
#   string self_url()
#
# Description:
#
#   Returns URL of corrent page with session information appended to
#   the query string.
#
#
# fmplib_session::get_hidden_session()
#
# Synopsis:
#
#   string get_hidden_session()
#
# Description:
#
#   Returns a form hidden input element containing the session id
#
#
# fmplib_session::get_hidden_id()
#
# Synopsis:
#
#   string get_hidden_id()
#
# Description:
#
#   Synonym for get_hidden_session()
#
#
# fmplib_session::hidden_id()
#
# Synopsis:
#
#   void hidden_id()
#
# Description:
#
#   Synonym for fmplib_session::hidden_session()
#
#
# fmplib_session::serialize()
#
# Synopsis:
#
#   string serialize()
#
# Description:
#
#   Get the serialized string of all session variables.
#
#
# fmplib_session::deserialize()
#
# Synopsis:
#
#   bool deserialize(string &$data_string)
#
# Description:
#
#   Decodes the session data in $data_string, setting variables stored in the
#   session.
#
#
# fmplib_session::freeze()
#
# Synopsis:
#
#   void freeze()
#
# Description:
#
#   Freezes all registered things (scalar variables, arrays, objects)
#   by saving all registered things to $_SESSION["fmplib"]["data"].
#
#
# fmplib_session::reimport_get_vars()
#
# Synopsis:
#
#   void reimport_get_vars()
#
# Description:
#
#   Reimport $_GET variables into the global namespace previously
#   overriden by session variables. 
#
#
# fmplib_session::reimport_post_vars()
#
# Synopsis:
#
#   void reimport_post_vars()
#
# Description:
#
#	Reimport $_POST variables into the global namespace previously
#	overriden by session variables.  @see  reimport_get_vars(),
#	reimport_cookie_vars()
# 
#
# fmplib_session::reimport_cookie_vars()
#
# Synopsis:
#
#   void reimport_cookie_vars()
#
# Description:
#
#	Reimport $_COOKIE variables into the global namespace previously
#	overriden by session variables.  @see  reimport_post_vars(),
#	reimport_get_vars().
#   
#
# fmplib_session::reimport_any_vars()
#
# Synopsis:
#
#   void reimport_any_vars(string $arrayname)
#
# Description:
#
#   Import any array specified by $arrayname into the $_GLOBAL scope.
#
# {{{ fmplib_session Class
class fmplib_session {
	// {{{ Instance variables
	// Class name.  This is kept for backward compatibility, although
	// it's not been useful since PHP3.  If $classname is set in a
	// child class, and $name is NOT set, then the the session cookie
	// is named according to the value of $classname.  $classname is
	// set by the constructor to the name of the defining class using
	// get_class().
	protected $classname;

	// Name of the autoinit-File, if any.
	public $auto_init;

	// Current session id
	public $id;

	// [Current] Session name
	private $name;
	protected $cookiename; // synonym for $name

	public $cookie_path;
	public $lifetime;

	// If set, the domain for which the session cookie is set
	public $cookie_domain;

	// fmplib_session will allow session mode setting only if
	// session.auto_start isn't set, and if no other class or call to
	// session_start() has previously started or resumed a session for
	// the request.  $mode and $fallback_mode must be set to either
	// "cookie" or "get".  The default is "cookie" for both, and is
	// the recommended, most secure setting.  
	//
	// Note well that using URL based session tracking ("get" mode)
	// constitutes a security risk and should be avoided if having a
	// 3rd party "steal" a session would be a problem, e.g. if private
	// personal data is involved.
	//
	// Note also that absolute URLs are not handled by PHP's native
	// URL-based session management, for obvious reasons.  Use
	// relative URLs for internal links if you want to implement
	// URL-based session tracking.
	//
	public $mode;
	public $fallback_mode;
	private $trans_id_enabled;
	private $session_cookie_set;

	// See options for session_cache_limit()
	public $allowcache;

	// Are we starting a new session, or piggybacking on top of one
	// that's already started?
	public $new_sess;

	// Do we want the session name to track the class name, or use the
	// php.ini value of the session ID.
	public $use_classname;

	// }}}
	// {{{ Constructor
	function __construct() {
		// determine if we are the dominant session
		//
		$this->new_sess = is_array($_SESSION) ? false : true;

		// Set public variables
		if (empty($this->allowcache)) 		$this->allowcache = 'nocache';
		if (empty($this->auto_init)) 		$this->auto_init = "";
		if (empty($this->id))				$this->id = "";
		if (!empty($this->cookiename)) 		$this->name = $this->cookiename;
		if (empty($this->cookie_path))		$this->cookie_path = "/";
		if (empty($this->cookie_domain))	$this->cookie_domain = '';
		if (empty($this->lifetime))			$this->lifetime = 0;
		if (empty($this->mode))				$this->mode = "cookie";
		if (empty($this->fallback_mode))	$this->fallback_mode = "cookie";
		if (empty($this->classname))		$this->classname = get_class($this);

		$this->set_tokenname();
		$this->put_headers();
		$this->set_sessionmode();
		$this->trans_id_enabled = ini_get("session.use_trans_sid") ? true : false;
		if ($this->new_sess) session_start();
		$this->id = session_id();
		$this->session_cookie_set = is_array($_COOKIE) && isset($_COOKIE[$name]) ? true : false;
		if(is_array($_SESSION["fmplib"]["data"])) {
			foreach ($_SESSION["fmplib"]["data"] as $key => $value) {
				global $$key;
				$$key=$value;
			}
		}
		$_SESSION["fmplib"]["Admin"]["new_sess"] = $this->new_sess;
		if (empty($_SESSION["fmplib"]["Admin"]["auto_init"]) && $this->auto_init) {
			include_once $this->auto_init;
			$_SESSION["fmplib"]["Admin"]["auto_init"] = true;
		}
	} 
	
	// }}} end constructor
	// {{{ Destructor
	function __destruct() {
		$this->freeze();
		if (!$this->new_sess) $_SESSION["fmplib"]["Admin"]["new_sess"] = $this->new_sess;
	}

	// }}}
	// {{{ public name()
	/**
	* Returns the name of the current session
	*
	* @return string  session_name() return value
	* @access public  
	*/
	function name() {
		return session_name();
 	}

	// }}}
	// {{{ private set_sessionmode()
	/**
	 * Set session support mode to cookie or URL
	 *
	 */
	private function set_sessionmode() {
		if ($this->new_sess) {
			if (($this->mode == "cookie") && ($this->fallback_mode == "cookie")) {
				ini_set("session.use_cookies", true);
				ini_set("session.use_only_cookies", true);
				ini_set("session.use_trans_sid", false);
			} elseif (($this->mode == "cookie") && ($this->fallback_mode == "get")) {
				ini_set("session.use_cookies", true);
				ini_set("session.use_only_cookies", false);
				ini_set("session.use_trans_sid", true);
			} elseif ($this->mode == "get") {
				ini_set("session.use_cookies", false);
				ini_set("session.use_only_cookies", false);
				ini_set("session.use_trans_sid", true);
			}
		}
	}

	// }}}
	// {{{ public new_id()
	/**
	* Start new session with new session ID
	*
	* @return string  current session id
	* @access public
	*/
	function new_id() {
		// Only do this if the session belongs to this class
		if ($this->new_sess) {
			$ok = session_regenerate_id(true);
		} else $ok = false;
		return $ok;
   	}

	// }}}
	// {{{ public get_id()
	/**
	* @brother id()
	* @deprec  $Id: session4.inc,v 1.3 2002/11/08 18:32:58 joestewart Exp $
	* @access public
	* What purpose, this??
	*/  
	function get_id() {
	  return $this->id;
	} // end func get_id

	// }}}
	// {{{ public register()
	/**
	* Register the variable(s) that should become persistent.
	*
	* @param   mixed String with the name of one or more variables seperated by comma
	*                 or a list of variables names: "foo"/"foo,bar,baz"/{"foo","bar","baz"}
	* @access public  
	*/
	function register ($var_names) {
		if (!is_array($var_names)) {
      		// spaces spoil everything
      		$var_names = trim($var_names);
      		$var_names=explode(",", $var_names);
		}
		foreach ($var_names as $key => $value ) {
			global $$value;
			if (!isset($_SESSION["fmplib"]["data"][$value])){
			$_SESSION["fmplib"]["data"][$value]= $$value;
        }
      }
	}
	
	// }}}
	// {{{ public is_registered()
	/**
	* see if a variable is registered in the current session
	*
	* @param  $var_name a string with the variable name 
	* @return false if variable not registered true on success.
	* @access public   
	*/
	function is_registered ($var_name) {
		$var_name = trim($var_name);  // to be sure
		return isset($_SESSION["fmplib"]["data"][$var_name]);
	}

	/// }}}
	// {{{ public unregister()
	/**
	* Recall the session registration for named variable(s)
	*
	* @param	  mixed   String with the name of one or more variables seperated by comma
	*                   or a list of variables names: "foo"/"foo,bar,baz"/{"foo","bar","baz"}
	* @access public  
	*/
	function unregister ($var_names) {
		$ok = true;

		foreach (explode (',', $var_names) as $var_name) {
			$var_name=trim($var_name);
			unset($_SESSION["fmplib"]["data"][$var_name]);
		}
		return $ok;
	}

	// }}}
    // {{{ public put_id()
	/**
	* Delete the cookie holding the session id.
	* 
	* RFC: is this really needed? can we prune this function?
	* 		 the only reason to keep it is if one wants to also
	*		 unset the cookie when session_destroy()ing,which PHP
	*		 doesn't seem to do (looking @ the session.c:940)
	* uw: yes we should keep it to remain the same interface, but deprec. 
	*
	* @deprec $Id: session4.inc,v 1.3 2002/11/08 18:32:58 joestewart Exp $
	* @access public  
	* @global $HTTP_COOKIE_VARS
	*/
	function put_id() {
		if ($this->new_sess) {
			if (get_cfg_var ('session.use_cookies') == 1) {
				$cookie_params = session_get_cookie_params();
				setCookie($this->name, '', 0, $cookie_params['path'], $cookie_params['domain']);
				$_COOKIE[$this->name] = "";
			}
			return true;
    	} else {
			return false;
		}
		return $this->new_sess;
	}

	// }}}
	// {{{ public delete()
	/**
	* Delete the current session destroying all registered data.
	* 
	* Note that it does more but the PHP 4 session_destroy it also 
	* throws away a cookie is there's one.
	*
	* @return boolean session_destroy return value
	* @access public  
	*/
	function delete() {
		unset($_SESSION["fmplib"]);
		if ($this->new_sess) {
			$ok = session_destroy();
			$this->put_id();
			return $ok;
		} else {
			return false;
		}
	}

	// }}}
	// {{{ public url()
	/**
	* Helper function: returns $url concatenated with the current session id
	* 
	* @param	$url	  URL to which the session id will be appended
	* @return string  rewritten url with session id included
	* @see    $trans_id_enabled
	* @global $_COOKIE
	* @deprec $Id: session4.inc,v 1.3 2002/11/08 18:32:58 joestewart Exp $
	* @access public  
	*/
	function url($url) {
		if (!$this->trans_id_enabled) 
		  return $url;

		$aUrl = parse_url($url);
		# we clean any(also bogus) sess in url
		if (!empty($aUrl["query"])) {
			$aUrl["query"] =  ereg_replace("([&?])".quotemeta(urlencode($this->name))."=(.)*(&|$)","\\1", $aUrl["query"]);
			# Remove trailing ?/& if needed
			$aUrl["query"] = ereg_replace("[&?]+$", "", $aUrl["query"]);
		} else {
			$aUrl["query"] = "";
		}

		if ((!$_COOKIE[$this->name]) || ($this->mode == "get")) {
			$aQy = array($this->name => $this->id);
			$qy = http_build_query($aQy);
		} else {
			$qy = "";
    	}
		$url = $aUrl["scheme"] . "://" . $aUrl["host"] . $aUrl["path"];

		if ($aUrl["query"] || $qy) {
			$url .= "?";
			if ($aUrl["query"] xor $qy) {
				$url .= $aUrl["query"] . $qy;
			} else {
				$url .= $aUrl["query"] . "&" . $qy;
			}
		}

		return $url;
	}

	// }}}
	// {{{ public purl()
	/**
	* @brother url()
	*/  
	function purl($url) {
		print $this->url($url);
	} // end func purl

	// }}}
	// {{{ public self_url()
	/**
	* Get current request URL.
	* 
	* WARNING: I'm not sure with the $this->url() call. Can someone check it?
	* WARNING: Apache variable $REQUEST_URI used - 
	* this it the best you can get but there's warranty the it's set beside 
	* the Apache world.
	* 
	* @return string
	* @global $REQUEST_URI
	* @access public  
	*/
	function self_url() {
		return $this->url($_SERVER["PHP_SELF"] . 
		  ((isset($_SERVER["QUERY_STRING"]) && ("" != $_SERVER["QUERY_STRING"]))
			? "?" . $_SERVER["QUERY_STRING"] : ""));
	}

	// }}}
	// {{{ public pself_url()
	/**
	* Print the current URL
	* @return void
	*/
	function pself_url() {
	  print $this->self_url();
	} // end func pself_url

	// }}}
	// {{{ public get_hidden_session()
	/**
	* Stores session id in a hidden variable (part of a form).
	*
	* @return string
	* @access public  
	*/
	function get_hidden_session() {
		if (!$this->trans_id_enabled) 
			return "";
		else 
			return sprintf('<input type="hidden" name="%s" value="%s" />', 
						$this->name, 
						$this->id);
	}

	// }}}
	// {{{ public hidden_session()
	/**
	* @brother  get_hidden_session
	* @return   void
	*/
	function hidden_session() {
	  print $this->get_hidden_session();
	} // end func hidden_session

	// }}}
	// {{{ public get_hidden_session()
	/**
	* @brother get_hidden_session
	*/
	function get_hidden_id() {
	  return $this->get_hidden_session();
	} // end func get_hidden_id

	// }}}
	// {{{ public hidden_id()
	/**
	* @brother hidden_session
	*/
	function hidden_id() {
	  print $this->get_hidden_session();
	} // end func hidden_id

	// }}}
	// {{{ public serialize()
	/**
	* Get the serialized string of session variables
	* 
	* Note that the serialization format is different from what it 
	* was in session3.inc. So clear all session data when switching 
	* to the PHP 4 code, it's not possible to load old session. 
	* 
	* @return string
	*/
	function serialize() {
	  return session_encode();
	} // end func serialze

	// }}}
	// {{{ public deserialize()
	/**
	* Import (session) variables from a string 
	* 
	* @param  string
	*
	* @return boolean
	*/
	function deserialize (&$data_string) {
	  return session_decode($data_string);
	} // end func deserialize

	// }}} 
	// {{{ public freeze()
	/**
	* freezes all registered things ( scalar variables, arrays, objects )
	* by saving all registered things to $_SESSION["fmplib"]["data"].
	*
	* @access public
	*
	*
	*/
	function freeze() {
		if (is_array($_SESSION["fmplib"]["data"])) {
			reset($_SESSION["fmplib"]["data"]);
			while(list($key,) = each($_SESSION["fmplib"]["data"])) {
				global $$key;
			eval("\$_SESSION['fmplib']['data'][\$key]= \$$key;");
			}
		}
	}

	// }}}
	// {{{ private set_tokenname()
	/**
	* ?
	* 
	*/
	private function set_tokenname() {
		if (!$this->cookie_domain) {
			$this->cookie_domain = get_cfg_var("session.cookie_domain");
		}
		if (!$this->cookie_path && get_cfg_var('session.cookie_path')) {
			$this->cookie_path = get_cfg_var('session.cookie_path');
		} elseif (!$this->cookie_path) {
			$this->cookie_path = "/";
		}

		if ($this->lifetime > 0) {
		  $lifetime = $this->lifetime*60;
		} else {
		  $lifetime = 0;
		}

		if ($this->new_sess) {
			if (!$this->name) {
				$this->name = $this->use_classname ? $this->classname : session_name();
			}
			ini_set("session.name", $this->name);
			session_set_cookie_params($lifetime, $this->cookie_path, $this->cookie_domain);
		} else {
			$this->name = session_name();
		}
	}

	// }}}
	// {{{ private put_headers()
	/**
	* ?
	*
	*/
	private function put_headers() {
		# set session.cache_limiter corresponding to $this->allowcache.
		if ($this->new_sess) {
			switch ($this->allowcache) {
			  case "passive":
			  case "public":
				session_cache_limiter ("public");  
				break;
			
			  case "private":
				session_cache_limiter ("private"); 
				break;
	
			  default:
				session_cache_limiter ("nocache");  
				break;
			}
		}
	} // end func put_headers


	// }}}
	// {{{ public reimport_get_vars()
	/**
	* Reimport $_GET into the global namespace previously overriden by session variables.
	* @see  reimport_post_vars(), reimport_cookie_vars()
	*/
	function reimport_get_vars() {
	  $this->reimport_any_vars("_GET");
	} // end func reimport_get_vars
	
	// }}}
	// {{{ reimport_post_vars()
	/**
	* Reimport $_POST variables into the global namespace previously
	* overriden by session variables.  @see  reimport_get_vars(),
	* reimport_cookie_vars()
	*/
	function reimport_post_vars() {
	  $this->reimport_any_vars("_POST");
	} // end func reimport_post_vars

	// }}}
	// {{{ public reimport_cookie_vars()
	/**
	* Reimport $_COOKIE variables into the global namespace previously
	* overriden by session variables.  @see  reimport_post_vars(),
	* reimport_get_vars()
	*/
	function reimport_cookie_vars() {
	  $this->reimport_any_vars("_COOKIE");
	} // end func reimport_cookie_vars

	// }}}
	// {{{ public reimport_any_vars()
	/**
	*
	* @var  array
	*/
	function reimport_any_vars($arrayname) {
	  global $$arrayname;
	  $GLOBALS = array_merge ($GLOBALS, $arrayname);
	} // end func reimport_any_vars

	// }}}
} // end class session
# }}}
?>