CHttpSession

Package system.web
Inheritance class CHttpSession » CApplicationComponent » CComponent
Implements IApplicationComponent, IteratorAggregate, Traversable, ArrayAccess, Countable
Subclasses CCacheHttpSession, CDbHttpSession
Since 1.0
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

Property Type Description Defined 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 Returns the number of items in the session. CHttpSession
gCProbability float the probability (percentage) that the gc (garbage collection) process is started on every session initialization, defaults to 1 meaning 1% chance. CHttpSession
isInitialized boolean Checks if this application component has been initialized. 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 {@link http://php. 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

Method Description Defined 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
evaluateExpression() Evaluates a PHP expression or callback under the context of this component. CComponent
gcSession() Session GC (garbage collection) handler. CHttpSession
get() Returns the session variable value with the session variable name. 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 items in the session. 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 if this application component has been initialized. 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 http://php.net/session.save_path. 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
regenerateID() Updates the current session id with a newly generated one . 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.

count property read-only

public integer getCount()

Returns the number of items in the session.

gCProbability property

public float getGCProbability()
public void setGCProbability(float $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 http://php.net/session.save_path.

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 overridden 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#490 (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#515 (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#131 (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#366 (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#525 (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#446 (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#140 (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#403 (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#415 (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.

get() method (available since v1.1.2)

public mixed get(mixed $key, mixed $defaultValue=NULL)
$key mixed the session variable name
$defaultValue mixed the default value to be returned when the session variable does not exist.
{return} mixed the session variable value, or $defaultValue if the session variable does not exist.
Source Code: framework/web/CHttpSession.php#468 (show)
public function get($key,$defaultValue=null)
{
    return isset(
$_SESSION[$key]) ? $_SESSION[$key] : $defaultValue;
}

Returns the session variable value with the session variable name. This method is very similar to itemAt and offsetGet, except that it will return $defaultValue if the session variable does not exist.

getCookieMode() method

public string getCookieMode()
{return} string how to use cookie to store session ID. Defaults to 'Allow'.
Source Code: framework/web/CHttpSession.php#255 (show)
public function getCookieMode()
{
    if(
ini_get('session.use_cookies')==='0')
        return 
'none';
    elseif(
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#228 (show)
public function getCookieParams()
{
    return 
session_get_cookie_params();
}

getCount() method

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

Returns the number of items in the session.

getGCProbability() method

public float getGCProbability()
{return} float 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#293 (show)
public function getGCProbability()
{
    return (float)(
ini_get('session.gc_probability')/ini_get('session.gc_divisor')*100);
}

getIsStarted() method

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

getIterator() method

public CHttpSessionIterator getIterator()
{return} CHttpSessionIterator an iterator for traversing the session variables.
Source Code: framework/web/CHttpSession.php#427 (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#454 (show)
public function getKeys()
{
    return 
array_keys($_SESSION);
}

getSavePath() method

public string getSavePath()
{return} string the current session save path, defaults to http://php.net/session.save_path.
Source Code: framework/web/CHttpSession.php#206 (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#162 (show)
public function getSessionID()
{
    return 
session_id();
}

getSessionName() method

public string getSessionName()
{return} string the current session name
Source Code: framework/web/CHttpSession.php#190 (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#334 (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#101 (show)
public function getUseCustomStorage()
{
    return 
false;
}

Returns a value indicating whether to use custom session storage. This method should be overridden 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#318 (show)
public function getUseTransparentSessionID()
{
    return 
ini_get('session.use_trans_sid')==1;
}

init() method

public void init()
Source Code: framework/web/CHttpSession.php#83 (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#479 (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#543 (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#553 (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#563 (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#572 (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#109 (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();
    if(
YII_DEBUG && session_id()=='')
    {
        
$message=Yii::t('yii','Failed to start session.');
        if(
function_exists('error_get_last'))
        {
            
$error=error_get_last();
            if(isset(
$error['message']))
                
$message=$error['message'];
        }
        
Yii::log($messageCLogger::LEVEL_WARNING'system.web.CHttpSession');
    }
}

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#355 (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#378 (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.

regenerateID() method (available since v1.1.8)

public void regenerateID(boolean $deleteOldSession=false)
$deleteOldSession boolean Whether to delete the old associated session file or not.
Source Code: framework/web/CHttpSession.php#181 (show)
public function regenerateID($deleteOldSession=false)
{
    if(
$this->getIsStarted())
        
session_regenerate_id($deleteOldSession);
}

Updates the current session id with a newly generated one . Please refer to http://php.net/session_regenerate_id for more details.

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#500 (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#269 (show)
public function setCookieMode($value)
{
    if(
$value==='none')
    {
        
ini_set('session.use_cookies','0');
        
ini_set('session.use_only_cookies','0');
    }
    elseif(
$value==='allow')
    {
        
ini_set('session.use_cookies','1');
        
ini_set('session.use_only_cookies','0');
    }
    elseif(
$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, httponly. Note that httponly is all lowercase.
Source Code: framework/web/CHttpSession.php#241 (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.

setGCProbability() method

public void setGCProbability(float $value)
$value float the probability (percentage) that the gc (garbage collection) process is started on every session initialization.
Source Code: framework/web/CHttpSession.php#302 (show)
public function setGCProbability($value)
{
    if(
$value>=&& $value<=100)
    {
        
// percent * 21474837 / 2147483647 ≈ percent * 0.01
        
ini_set('session.gc_probability',floor($value*21474836.47));
        
ini_set('session.gc_divisor',2147483647);
    }
    else
        throw new 
CException(Yii::t('yii','CHttpSession.gcProbability "{value}" is invalid. It must be a float 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#215 (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#170 (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#198 (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#342 (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#326 (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#533 (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#391 (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.

© 2008–2017 by Yii Software LLC
Licensed under the three clause BSD license.
http://www.yiiframework.com/doc/api/1.1/CHttpSession