Saving Data * * You can write a value to a users session from your PHP code using the static function {@link Session::set()}. You * can add this line in any function or file you wish to save the value. * * * Session::set('MyValue', 6); * * * Saves the value of "6" to the MyValue session data. You can also save arrays or serialized objects in session (but * note there may be size restrictions as to how much you can save) * * * // save a variable * $var = 1; * Session::set('MyVar', $var); * * // saves an array * Session::set('MyArrayOfValues', array('1','2','3')); * * // saves an object (you'll have to unserialize it back) * $object = new Object(); * * Session::set('MyObject', serialize($object)); * * * Accessing Data * * Once you have saved a value to the Session you can access it by using the {@link Session::get()} function. * Like the {@link Session::set()} function you can use this anywhere in your PHP files. * * The values in the comments are the values stored from the previous example. * * * public function bar() { * $value = Session::get('MyValue'); // $value = 6 * $var = Session::get('MyVar'); // $var = 1 * $array = Session::get('MyArrayOfValues'); // $array = array(1,2,3) * $object = Session::get('MyObject', unserialize($object)); // $object = Object() * } * * * You can also get all the values in the session at once. This is useful for debugging. * * * Session::get_all(); // returns an array of all the session values. * * * Clearing Data * * Once you have accessed a value from the Session it doesn't automatically wipe the value from the Session, you have * to specifically remove it. To clear a value you can either delete 1 session value by the name that you saved it * * * Session::clear('MyValue'); // myvalue is no longer 6. * * * Or you can clear every single value in the session at once. Note SilverStripe stores some of its own session data * including form and page comment information. None of this is vital but clear_all will clear everything. * * * Session::clear_all(); * * * @see Cookie * @todo This class is currently really basic and could do with a more well-thought-out implementation. * * @package framework * @subpackage control */ class Session { /** * @var $timeout Set session timeout */ protected static $timeout = 0; protected static $session_ips = array(); protected static $cookie_domain; protected static $cookie_path; protected static $session_store_path; protected static $cookie_secure = false; /** * Session data */ protected $data = array(); protected $changedData = array(); /** * Start PHP session, then create a new Session object with the given start data. * * @param $data Can be an array of data (such as $_SESSION) or another Session object to clone. */ public function __construct($data) { if($data instanceof Session) $data = $data->inst_getAll(); $this->data = $data; } /** * Cookie domain, for example 'www.php.net'. * * To make cookies visible on all subdomains then the domain * must be prefixed with a dot like '.php.net'. * * @param string $domain The domain to set */ public static function set_cookie_domain($domain) { self::$cookie_domain = $domain; } /** * Get the cookie domain. * @return string */ public static function get_cookie_domain() { return self::$cookie_domain; } /** * Path to set on the domain where the session cookie will work. * Use a single slash ('/') for all paths on the domain. * * @param string $path The path to set */ public static function set_cookie_path($path) { self::$cookie_path = $path; } /** * Get the path on the domain where the session cookie will work. * @return string */ public static function get_cookie_path() { if(self::$cookie_path) { return self::$cookie_path; } else { return Director::baseURL(); } } /** * Secure cookie, tells the browser to only send it over SSL. * @param boolean $secure */ public static function set_cookie_secure($secure) { self::$cookie_secure = (bool) $secure; } /** * Get if the cookie is secure * @return boolean */ public static function get_cookie_secure() { return (bool) self::$cookie_secure; } /** * Set the session store path * @param string $path Filesystem path to the session store */ public static function set_session_store_path($path) { self::$session_store_path = $path; } /** * Get the session store path * @return string */ public static function get_session_store_path() { return self::$session_store_path; } /** * Provide an array of rules specifing timeouts for IPv4 address ranges or * individual IPv4 addresses. The key is an IP address or range and the value is the time * until the session expires in seconds. For example: * * Session::set_timeout_ips(array( * '127.0.0.1' => 36000 * )); * * Any user connecting from 127.0.0.1 (localhost) will have their session expired after 10 hours. * * Session::set_timeout is used to set the timeout value for any users whose address is not in the given IP range. * * @param array $session_ips Array of IPv4 rules. */ public static function set_timeout_ips($session_ips) { if(!is_array($session_ips)) { user_error("Session::set_timeout_ips expects an array as its argument", E_USER_NOTICE); self::$session_ips = array(); } else { self::$session_ips = $session_ips; } } /** * Add a value to a specific key in the session array */ public static function add_to_array($name, $val) { return self::current_session()->inst_addToArray($name, $val); } /** * Set a key/value pair in the session * * @param string $name Key * @param string $val Value */ public static function set($name, $val) { return self::current_session()->inst_set($name, $val); } /** * Return a specific value by session key * * @param string $name Key to lookup */ public static function get($name) { return self::current_session()->inst_get($name); } /** * Return all the values in session * * @return Array */ public static function get_all() { return self::current_session()->inst_getAll(); } /** * Clear a given session key, value pair. * * @param string $name Key to lookup */ public static function clear($name) { return self::current_session()->inst_clear($name); } /** * Clear all the values * * @return void */ public static function clear_all() { self::current_session()->inst_clearAll(); self::$default_session = null; } /** * Save all the values in our session to $_SESSION */ public static function save() { return self::current_session()->inst_save(); } protected static $default_session = null; protected static function current_session() { if(Controller::has_curr()) { return Controller::curr()->getSession(); } else { if(!self::$default_session) self::$default_session = new Session(isset($_SESSION) ? $_SESSION : array()); return self::$default_session; } } public function inst_set($name, $val) { // Quicker execution path for "."-free names if(strpos($name,'.') === false) { $this->data[$name] = $val; $this->changedData[$name] = $val; } else { $names = explode('.', $name); // We still want to do this even if we have strict path checking for legacy code $var = &$this->data; $diffVar = &$this->changedData; // Iterate twice over the names - once to see if the value needs to be changed, // and secondly to get the changed data value. This is done to solve a problem // where iterating over the diff var would create empty arrays, and the value // would then not be set, inadvertently clearing session values. foreach($names as $n) { $var = &$var[$n]; } if($var !== $val) { foreach($names as $n) { $diffVar = &$diffVar[$n]; } $var = $val; $diffVar = $val; } } } public function inst_addToArray($name, $val) { $names = explode('.', $name); // We still want to do this even if we have strict path checking for legacy code $var = &$this->data; $diffVar = &$this->changedData; foreach($names as $n) { $var = &$var[$n]; $diffVar = &$diffVar[$n]; } $var[] = $val; $diffVar[sizeof($var)-1] = $val; } public function inst_get($name) { // Quicker execution path for "."-free names if(strpos($name,'.') === false) { if(isset($this->data[$name])) return $this->data[$name]; } else { $names = explode('.', $name); if(!isset($this->data)) { return null; } $var = $this->data; foreach($names as $n) { if(!isset($var[$n])) { return null; } $var = $var[$n]; } return $var; } } public function inst_clear($name) { $names = explode('.', $name); // We still want to do this even if we have strict path checking for legacy code $var = &$this->data; $diffVar = &$this->changedData; foreach($names as $n) { // don't clear a record that doesn't exist if(!isset($var[$n])) return; $var = &$var[$n]; } // only loop to find data within diffVar if var is proven to exist in the above loop foreach($names as $n) { $diffVar = &$diffVar[$n]; } if($var !== null) { $var = null; $diffVar = null; } } public function inst_clearAll() { if($this->data && is_array($this->data)) { foreach(array_keys($this->data) as $key) { $this->inst_clear($key); } } } public function inst_getAll() { return $this->data; } /** * Save data to session * Only save the changes, so that anyone manipulating $_SESSION directly doesn't get burned. */ public function inst_save() { if($this->changedData) { if(!isset($_SESSION)) Session::start(); $this->recursivelyApply($this->changedData, $_SESSION); } } /** * Recursively apply the changes represented in $data to $dest. * Used to update $_SESSION */ protected function recursivelyApply($data, &$dest) { foreach($data as $k => $v) { if(is_array($v)) { if(!isset($dest[$k]) || !is_array($dest[$k])) $dest[$k] = array(); $this->recursivelyApply($v, $dest[$k]); } else { $dest[$k] = $v; } } } /** * Return the changed data, for debugging purposes. * @return array */ public function inst_changedData() { return $this->changedData; } /** * Sets the appropriate form message in session, with type. This will be shown once, * for the form specified. * * @param formname the form name you wish to use ( usually $form->FormName() ) * @param messsage the message you wish to add to it * @param type the type of message */ public static function setFormMessage($formname,$message,$type){ Session::set("FormInfo.$formname.message", $message); Session::set("FormInfo.$formname.type", $type); } /** * Initialize session. * * @param string $sid Start the session with a specific ID */ public static function start($sid = null) { $path = self::get_cookie_path(); $domain = self::get_cookie_domain(); $secure = self::get_cookie_secure(); $session_path = self::get_session_store_path(); if(!session_id() && !headers_sent()) { if($domain) { session_set_cookie_params(self::$timeout, $path, $domain, $secure /* secure */, true /* httponly */); } else { session_set_cookie_params(self::$timeout, $path, null, $secure /* secure */, true /* httponly */); } // Allow storing the session in a non standard location if($session_path) session_save_path($session_path); // @ is to supress win32 warnings/notices when session wasn't cleaned up properly // There's nothing we can do about this, because it's an operating system function! if($sid) session_id($sid); @session_start(); } } /** * Destroy the active session. * * @param bool $removeCookie If set to TRUE, removes the user's cookie, FALSE does not remove */ public static function destroy($removeCookie = true) { if(session_id()) { if($removeCookie) { $path = self::get_cookie_path(); $domain = self::get_cookie_domain(); $secure = self::get_cookie_secure(); if($domain) { setcookie(session_name(), '', null, $path, $domain, $secure, true); } else { setcookie(session_name(), '', null, $path, null, $secure, true); } unset($_COOKIE[session_name()]); } session_destroy(); } } /** * Set the timeout of a Session value * * @param int $timeout Time until a session expires in seconds. Defaults to expire when browser is closed. */ public static function set_timeout($timeout) { self::$timeout = intval($timeout); } public static function get_timeout() { return self::$timeout; } }