0 follower

CHttpSession

Package system.web
Inheritance class CHttpSession » CApplicationComponent » CComponent
Implements IApplicationComponent, IteratorAggregate, Traversable, ArrayAccess, Countable
Subclasses CCacheHttpSession, CDbHttpSession
Since 1.0
Version $Id$
Source Code framework/web/CHttpSession.php
CHttpSession provides session-level data management and the related configurations.

To start the session, call open(); To complete and send out session data, call close(); To destroy the session, call destroy().

If autoStart is set true, the session will be started automatically when the application component is initialized by the application.

CHttpSession can be used like an array to set and get session data. For example, 
  $session=new CHttpSession;
  $session->open();
  $value1=$session['name1'];  // get session variable 'name1'
  $value2=$session['name2'];  // get session variable 'name2'
  foreach($session as $name=>$value) // traverse all session variables
  $session['name3']=$value3;  // set session variable 'name3'


The following configurations are available for session: See the corresponding setter and getter documentation for more information. Note, these properties must be set before the session is started.

CHttpSession can be extended to support customized session storage. Override openSession, closeSession, readSession, writeSession, destroySession and gcSession and set useCustomStorage to true. Then, the session data will be stored and retrieved using the above methods.

CHttpSession is a Web application component that can be accessed via CWebApplication::getSession().

Public Properties

Hide inherited properties

PropertyTypeDescriptionDefined By
autoStart boolean whether the session should be automatically started when the session application component is initialized, defaults to true. CHttpSession
behaviors array the behaviors that should be attached to this component. CApplicationComponent
cookieMode string how to use cookie to store session ID. CHttpSession
cookieParams array the session cookie parameters. CHttpSession
count integer the number of session variables CHttpSession
gCProbability integer the probability (percentage) that the gc (garbage collection) process is started on every session initialization, defaults to 1 meaning 1% chance. CHttpSession
isInitialized boolean whether this application component has been initialized (i.e., init() is invoked. CApplicationComponent
isStarted boolean whether the session has started CHttpSession
iterator CHttpSessionIterator Returns an iterator for traversing the session variables. CHttpSession
keys array the list of session variable names CHttpSession
savePath string the current session save path, defaults to '/tmp'. CHttpSession
sessionID string the current session ID CHttpSession
sessionName string the current session name CHttpSession
timeout integer the number of seconds after which data will be seen as 'garbage' and cleaned up, defaults to 1440 seconds. CHttpSession
useCustomStorage boolean Returns a value indicating whether to use custom session storage. CHttpSession
useTransparentSessionID boolean whether transparent sid support is enabled or not, defaults to false. CHttpSession

Public Methods

Hide inherited methods

MethodDescriptionDefined By
__call() Calls the named method which is not a class method. CComponent
__get() Returns a property value, an event handler list or a behavior based on its name. CComponent
__isset() Checks if a property value is null. CComponent
__set() Sets value of a component property. CComponent
__unset() Sets a component property to be null. CComponent
add() Adds a session variable. CHttpSession
asa() Returns the named behavior object. CComponent
attachBehavior() Attaches a behavior to this component. CComponent
attachBehaviors() Attaches a list of behaviors to the component. CComponent
attachEventHandler() Attaches an event handler to an event. CComponent
canGetProperty() Determines whether a property can be read. CComponent
canSetProperty() Determines whether a property can be set. CComponent
clear() Removes all session variables CHttpSession
close() Ends the current session and store session data. CHttpSession
closeSession() Session close handler. CHttpSession
contains() CHttpSession
count() Returns the number of items in the session. CHttpSession
destroy() Frees all session variables and destroys all data registered to a session. CHttpSession
destroySession() Session destroy handler. CHttpSession
detachBehavior() Detaches a behavior from the component. CComponent
detachBehaviors() Detaches all behaviors from the component. CComponent
detachEventHandler() Detaches an existing event handler. CComponent
disableBehavior() Disables an attached behavior. CComponent
disableBehaviors() Disables all behaviors attached to this component. CComponent
enableBehavior() Enables an attached behavior. CComponent
enableBehaviors() Enables all behaviors attached to this component. CComponent
gcSession() Session GC (garbage collection) handler. CHttpSession
getCookieMode() Returns how to use cookie to store session ID. Defaults to 'Allow'. CHttpSession
getCookieParams() Returns the session cookie parameters. CHttpSession
getCount() Returns the number of session variables CHttpSession
getEventHandlers() Returns the list of attached event handlers for an event. CComponent
getGCProbability() Returns the probability (percentage) that the gc (garbage collection) process is started on every session initialization, defaults to 1 meaning 1% chance. CHttpSession
getIsInitialized() Checks whether this application component has been initialized (i.e., init() is invoked.) CApplicationComponent
getIsStarted() Checks whether the session has started CHttpSession
getIterator() Returns an iterator for traversing the session variables. CHttpSession
getKeys() Returns the list of session variable names CHttpSession
getSavePath() Returns the current session save path, defaults to '/tmp'. CHttpSession
getSessionID() Returns the current session ID CHttpSession
getSessionName() Returns the current session name CHttpSession
getTimeout() Returns the number of seconds after which data will be seen as 'garbage' and cleaned up, defaults to 1440 seconds. CHttpSession
getUseCustomStorage() Returns a value indicating whether to use custom session storage. CHttpSession
getUseTransparentSessionID() Returns whether transparent sid support is enabled or not, defaults to false. CHttpSession
hasEvent() Determines whether an event is defined. CComponent
hasEventHandler() Checks whether the named event has attached handlers. CComponent
hasProperty() Determines whether a property is defined. CComponent
init() Initializes the application component. CHttpSession
itemAt() Returns the session variable value with the session variable name. CHttpSession
offsetExists() This method is required by the interface ArrayAccess. CHttpSession
offsetGet() This method is required by the interface ArrayAccess. CHttpSession
offsetSet() This method is required by the interface ArrayAccess. CHttpSession
offsetUnset() This method is required by the interface ArrayAccess. CHttpSession
open() Starts the session if it has not started yet. CHttpSession
openSession() Session open handler. CHttpSession
raiseEvent() Raises an event. CComponent
readSession() Session read handler. CHttpSession
remove() Removes a session variable. CHttpSession
setCookieMode() Sets how to use cookie to store session ID. Valid values include 'none', 'allow' and 'only'. CHttpSession
setCookieParams() Sets the session cookie parameters. CHttpSession
setGCProbability() Sets the probability (percentage) that the gc (garbage collection) process is started on every session initialization. CHttpSession
setSavePath() Sets the current session save path CHttpSession
setSessionID() Sets the session ID for the current session CHttpSession
setSessionName() Sets the session name for the current session, must be an alphanumeric string, defaults to PHPSESSID CHttpSession
setTimeout() Sets the number of seconds after which data will be seen as 'garbage' and cleaned up CHttpSession
setUseTransparentSessionID() Sets whether transparent sid support is enabled or not. CHttpSession
toArray() CHttpSession
writeSession() Session write handler. CHttpSession

Property Details

autoStart property
public boolean $autoStart;

whether the session should be automatically started when the session application component is initialized, defaults to true.

cookieMode property
public string getCookieMode()
public void setCookieMode(string $value)

how to use cookie to store session ID. Defaults to 'Allow'.

cookieParams property
public array getCookieParams()
public void setCookieParams(array $value)

the session cookie parameters.

See Also

count property read-only
public integer getCount()

the number of session variables

gCProbability property
public integer getGCProbability()
public void setGCProbability(integer $value)

the probability (percentage) that the gc (garbage collection) process is started on every session initialization, defaults to 1 meaning 1% chance.

isStarted property read-only
public boolean getIsStarted()

whether the session has started

iterator property read-only
public CHttpSessionIterator getIterator()

Returns an iterator for traversing the session variables. This method is required by the interface IteratorAggregate.

keys property read-only
public array getKeys()

the list of session variable names

savePath property
public string getSavePath()
public void setSavePath(string $value)

the current session save path, defaults to '/tmp'.

sessionID property
public string getSessionID()
public void setSessionID(string $value)

the current session ID

sessionName property
public string getSessionName()
public void setSessionName(string $value)

the current session name

timeout property
public integer getTimeout()
public void setTimeout(integer $value)

the number of seconds after which data will be seen as 'garbage' and cleaned up, defaults to 1440 seconds.

useCustomStorage property read-only
public boolean getUseCustomStorage()

Returns a value indicating whether to use custom session storage. This method should be overriden to return true if custom session storage handler should be used. If returning true, make sure the methods openSession, closeSession, readSession, writeSession, destroySession, and gcSession are overridden in child class, because they will be used as the callback handlers. The default implementation always return false.

useTransparentSessionID property
public boolean getUseTransparentSessionID()
public void setUseTransparentSessionID(boolean $value)

whether transparent sid support is enabled or not, defaults to false.

Method Details

add() method
public void add(mixed $key, mixed $value)
$key mixed session variable name
$value mixed session variable value
Source Code: framework/web/CHttpSession.php#431 (show)
public function add($key,$value)
{
    $_SESSION[$key]=$value;
}

Adds a session variable. Note, if the specified name already exists, the old value will be removed first.

clear() method
public void clear()
Source Code: framework/web/CHttpSession.php#456 (show)
public function clear()
{
    foreach(array_keys($_SESSION) as $key)
        unset($_SESSION[$key]);
}

Removes all session variables

close() method
public void close()
Source Code: framework/web/CHttpSession.php#106 (show)
public function close()
{
    if(session_id()!=='')
        @session_write_close();
}

Ends the current session and store session data.

closeSession() method
public boolean closeSession()
{return} boolean whether session is closed successfully
Source Code: framework/web/CHttpSession.php#322 (show)
public function closeSession()
{
    return true;
}

Session close handler. This method should be overridden if useCustomStorage is set true. Do not call this method directly.

contains() method
public boolean contains(mixed $key)
$key mixed session variable name
{return} boolean whether there is the named session variable
Source Code: framework/web/CHttpSession.php#466 (show)
public function contains($key)
{
    return isset($_SESSION[$key]);
}

count() method
public integer count()
{return} integer number of items in the session.
Source Code: framework/web/CHttpSession.php#401 (show)
public function count()
{
    return $this->getCount();
}

Returns the number of items in the session. This method is required by Countable interface.

destroy() method
public void destroy()
Source Code: framework/web/CHttpSession.php#115 (show)
public function destroy()
{
    if(session_id()!=='')
    {
        @session_unset();
        @session_destroy();
    }
}

Frees all session variables and destroys all data registered to a session.

destroySession() method
public boolean destroySession(string $id)
$id string session ID
{return} boolean whether session is destroyed successfully
Source Code: framework/web/CHttpSession.php#359 (show)
public function destroySession($id)
{
    return true;
}

Session destroy handler. This method should be overridden if useCustomStorage is set true. Do not call this method directly.

gcSession() method
public boolean gcSession(integer $maxLifetime)
$maxLifetime integer the number of seconds after which data will be seen as 'garbage' and cleaned up.
{return} boolean whether session is GCed successfully
Source Code: framework/web/CHttpSession.php#371 (show)
public function gcSession($maxLifetime)
{
    return true;
}

Session GC (garbage collection) handler. This method should be overridden if useCustomStorage is set true. Do not call this method directly.

getCookieMode() method
public string getCookieMode()
{return} string how to use cookie to store session ID. Defaults to 'Allow'.
Source Code: framework/web/CHttpSession.php#215 (show)
public function getCookieMode()
{
    if(ini_get('session.use_cookies')==='0')
        return 'none';
    else if(ini_get('session.use_only_cookies')==='0')
        return 'allow';
    else
        return 'only';
}

getCookieParams() method
public array getCookieParams()
{return} array the session cookie parameters.
Source Code: framework/web/CHttpSession.php#189 (show)
public function getCookieParams()
{
    return session_get_cookie_params();
}

See Also

getCount() method
public integer getCount()
{return} integer the number of session variables
Source Code: framework/web/CHttpSession.php#391 (show)
public function getCount()
{
    return count($_SESSION);
}

getGCProbability() method
public integer getGCProbability()
{return} integer the probability (percentage) that the gc (garbage collection) process is started on every session initialization, defaults to 1 meaning 1% chance.
Source Code: framework/web/CHttpSession.php#249 (show)
public function getGCProbability()
{
    return (int)ini_get('session.gc_probability');
}

getIsStarted() method
public boolean getIsStarted()
{return} boolean whether the session has started
Source Code: framework/web/CHttpSession.php#127 (show)
public function getIsStarted()
{
    return session_id()!=='';
}

getIterator() method
public CHttpSessionIterator getIterator()
{return} CHttpSessionIterator an iterator for traversing the session variables.
Source Code: framework/web/CHttpSession.php#383 (show)
public function getIterator()
{
    return new CHttpSessionIterator;
}

Returns an iterator for traversing the session variables. This method is required by the interface IteratorAggregate.

getKeys() method
public array getKeys()
{return} array the list of session variable names
Source Code: framework/web/CHttpSession.php#409 (show)
public function getKeys()
{
    return array_keys($_SESSION);
}

getSavePath() method
public string getSavePath()
{return} string the current session save path, defaults to '/tmp'.
Source Code: framework/web/CHttpSession.php#167 (show)
public function getSavePath()
{
    return session_save_path();
}

getSessionID() method
public string getSessionID()
{return} string the current session ID
Source Code: framework/web/CHttpSession.php#135 (show)
public function getSessionID()
{
    return session_id();
}

getSessionName() method
public string getSessionName()
{return} string the current session name
Source Code: framework/web/CHttpSession.php#151 (show)
public function getSessionName()
{
    return session_name();
}

getTimeout() method
public integer getTimeout()
{return} integer the number of seconds after which data will be seen as 'garbage' and cleaned up, defaults to 1440 seconds.
Source Code: framework/web/CHttpSession.php#290 (show)
public function getTimeout()
{
    return (int)ini_get('session.gc_maxlifetime');
}

getUseCustomStorage() method
public boolean getUseCustomStorage()
{return} boolean whether to use custom storage.
Source Code: framework/web/CHttpSession.php#88 (show)
public function getUseCustomStorage()
{
    return false;
}

Returns a value indicating whether to use custom session storage. This method should be overriden to return true if custom session storage handler should be used. If returning true, make sure the methods openSession, closeSession, readSession, writeSession, destroySession, and gcSession are overridden in child class, because they will be used as the callback handlers. The default implementation always return false.

getUseTransparentSessionID() method
public boolean getUseTransparentSessionID()
{return} boolean whether transparent sid support is enabled or not, defaults to false.
Source Code: framework/web/CHttpSession.php#274 (show)
public function getUseTransparentSessionID()
{
    return ini_get('session.use_trans_sid')==1;
}

init() method
public void init()
Source Code: framework/web/CHttpSession.php#71 (show)
public function init()
{
    parent::init();
    if($this->autoStart)
        $this->open();
    register_shutdown_function(array($this,'close'));
}

Initializes the application component. This method is required by IApplicationComponent and is invoked by application.

itemAt() method
public mixed itemAt(mixed $key)
$key mixed the session variable name
{return} mixed the session variable value, null if no such variable exists
Source Code: framework/web/CHttpSession.php#420 (show)
public function itemAt($key)
{
    return isset($_SESSION[$key]) ? $_SESSION[$key] : null;
}

Returns the session variable value with the session variable name. This method is exactly the same as offsetGet.

offsetExists() method
public boolean offsetExists(mixed $offset)
$offset mixed the offset to check on
{return} boolean
Source Code: framework/web/CHttpSession.php#484 (show)
public function offsetExists($offset)
{
    return isset($_SESSION[$offset]);
}

This method is required by the interface ArrayAccess.

offsetGet() method
public mixed offsetGet(integer $offset)
$offset integer the offset to retrieve element.
{return} mixed the element at the offset, null if no element is found at the offset
Source Code: framework/web/CHttpSession.php#494 (show)
public function offsetGet($offset)
{
    return isset($_SESSION[$offset]) ? $_SESSION[$offset] : null;
}

This method is required by the interface ArrayAccess.

offsetSet() method
public void offsetSet(integer $offset, mixed $item)
$offset integer the offset to set element
$item mixed the element value
Source Code: framework/web/CHttpSession.php#504 (show)
public function offsetSet($offset,$item)
{
    $_SESSION[$offset]=$item;
}

This method is required by the interface ArrayAccess.

offsetUnset() method
public void offsetUnset(mixed $offset)
$offset mixed the offset to unset element
Source Code: framework/web/CHttpSession.php#513 (show)
public function offsetUnset($offset)
{
    unset($_SESSION[$offset]);
}

This method is required by the interface ArrayAccess.

open() method
public void open()
Source Code: framework/web/CHttpSession.php#96 (show)
public function open()
{
    if($this->getUseCustomStorage())
        @session_set_save_handler(array($this,'openSession'),array($this,'closeSession'),array($this,'readSession'),array($this,'writeSession'),array($this,'destroySession'),array($this,'gcSession'));
    @session_start();
}

Starts the session if it has not started yet.

openSession() method
public boolean openSession(string $savePath, string $sessionName)
$savePath string session save path
$sessionName string session name
{return} boolean whether session is opened successfully
Source Code: framework/web/CHttpSession.php#311 (show)
public function openSession($savePath,$sessionName)
{
    return true;
}

Session open handler. This method should be overridden if useCustomStorage is set true. Do not call this method directly.

readSession() method
public string readSession(string $id)
$id string session ID
{return} string the session data
Source Code: framework/web/CHttpSession.php#334 (show)
public function readSession($id)
{
    return '';
}

Session read handler. This method should be overridden if useCustomStorage is set true. Do not call this method directly.

remove() method
public mixed remove(mixed $key)
$key mixed the name of the session variable to be removed
{return} mixed the removed value, null if no such session variable.
Source Code: framework/web/CHttpSession.php#441 (show)
public function remove($key)
{
    if(isset($_SESSION[$key]))
    {
        $value=$_SESSION[$key];
        unset($_SESSION[$key]);
        return $value;
    }
    else
        return null;
}

Removes a session variable.

setCookieMode() method
public void setCookieMode(string $value)
$value string how to use cookie to store session ID. Valid values include 'none', 'allow' and 'only'.
Source Code: framework/web/CHttpSession.php#228 (show)
public function setCookieMode($value)
{
    if($value==='none')
        ini_set('session.use_cookies','0');
    else if($value==='allow')
    {
        ini_set('session.use_cookies','1');
        ini_set('session.use_only_cookies','0');
    }
    else if($value==='only')
    {
        ini_set('session.use_cookies','1');
        ini_set('session.use_only_cookies','1');
    }
    else
        throw new CException(Yii::t('yii','CHttpSession.cookieMode can only be "none", "allow" or "only".'));
}

setCookieParams() method
public void setCookieParams(array $value)
$value array cookie parameters, valid keys include: lifetime, path, domain, secure.
Source Code: framework/web/CHttpSession.php#201 (show)
public function setCookieParams($value)
{
    $data=session_get_cookie_params();
    extract($data);
    extract($value);
    if(isset($httponly))
        session_set_cookie_params($lifetime,$path,$domain,$secure,$httponly);
    else
        session_set_cookie_params($lifetime,$path,$domain,$secure);
}

Sets the session cookie parameters. The effect of this method only lasts for the duration of the script. Call this method before the session starts.

See Also

setGCProbability() method
public void setGCProbability(integer $value)
$value integer the probability (percentage) that the gc (garbage collection) process is started on every session initialization.
Source Code: framework/web/CHttpSession.php#258 (show)
public function setGCProbability($value)
{
    $value=(int)$value;
    if($value>=0 && $value<=100)
    {
        ini_set('session.gc_probability',$value);
        ini_set('session.gc_divisor','100');
    }
    else
        throw new CException(Yii::t('yii','CHttpSession.gcProbability "{value}" is invalid. It must be an integer between 0 and 100.',
            array('{value}'=>$value)));
}

setSavePath() method
public void setSavePath(string $value)
$value string the current session save path
Source Code: framework/web/CHttpSession.php#176 (show)
public function setSavePath($value)
{
    if(is_dir($value))
        session_save_path($value);
    else
        throw new CException(Yii::t('yii','CHttpSession.savePath "{path}" is not a valid directory.',
            array('{path}'=>$value)));
}

setSessionID() method
public void setSessionID(string $value)
$value string the session ID for the current session
Source Code: framework/web/CHttpSession.php#143 (show)
public function setSessionID($value)
{
    session_id($value);
}

setSessionName() method
public void setSessionName(string $value)
$value string the session name for the current session, must be an alphanumeric string, defaults to PHPSESSID
Source Code: framework/web/CHttpSession.php#159 (show)
public function setSessionName($value)
{
    session_name($value);
}

setTimeout() method
public void setTimeout(integer $value)
$value integer the number of seconds after which data will be seen as 'garbage' and cleaned up
Source Code: framework/web/CHttpSession.php#298 (show)
public function setTimeout($value)
{
    ini_set('session.gc_maxlifetime',$value);
}

setUseTransparentSessionID() method
public void setUseTransparentSessionID(boolean $value)
$value boolean whether transparent sid support is enabled or not.
Source Code: framework/web/CHttpSession.php#282 (show)
public function setUseTransparentSessionID($value)
{
    ini_set('session.use_trans_sid',$value?'1':'0');
}

toArray() method
public array toArray()
{return} array the list of all session variables in array
Source Code: framework/web/CHttpSession.php#474 (show)
public function toArray()
{
    return $_SESSION;
}

writeSession() method
public boolean writeSession(string $id, string $data)
$id string session ID
$data string session data
{return} boolean whether session write is successful
Source Code: framework/web/CHttpSession.php#347 (show)
public function writeSession($id,$data)
{
    return true;
}

Session write handler. This method should be overridden if useCustomStorage is set true. Do not call this method directly.