Class CHttpSession

CHttpSession provides session-level data management and the related configurations.

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

If CHttpSession::$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:

setSessionID sessionID;
setSessionName sessionName;
CHttpSession::$autoStart;
setSavePath savePath;
setCookieParams cookieParams;
setGCProbability gcProbability;
setCookieMode cookieMode;
setUseTransparentSessionID useTransparentSessionID;
setTimeout timeout.

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 CHttpSession::openSession(), CHttpSession::closeSession(), CHttpSession::readSession(), CHttpSession::writeSession(), CHttpSession::destroySession() and CHttpSession::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().

CComponent

CApplicationComponent implements IApplicationComponent

CHttpSession implements IteratorAggregate, ArrayAccess, Countable

Direct known subclasses

CCacheHttpSession, CDbHttpSession

Package: system\web
Copyright: 2008-2013 Yii Software LLC
License: http://www.yiiframework.com/license/
Author: Qiang Xue <qiang.xue@gmail.com>
Since: 1.0
Located at x2engine/framework/web/CHttpSession.php

Methods summary
`public`	# `init( )` Initializes the application component. This method is required by IApplicationComponent and is invoked by application. Initializes the application component. This method is required by IApplicationComponent and is invoked by application. Overrides `CApplicationComponent::init()`
`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 `CHttpSession::openSession()`, `CHttpSession::closeSession()`, `CHttpSession::readSession()`, `CHttpSession::writeSession()`, `CHttpSession::destroySession()`, and `CHttpSession::gcSession()` are overridden in child class, because they will be used as the callback handlers. The default implementation always 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 `CHttpSession::openSession()`, `CHttpSession::closeSession()`, `CHttpSession::readSession()`, `CHttpSession::writeSession()`, `CHttpSession::destroySession()`, and `CHttpSession::gcSession()` are overridden in child class, because they will be used as the callback handlers. The default implementation always return false. Returns `boolean` whether to use custom storage.
`public`	# `open( )` Starts the session if it has not started yet. Starts the session if it has not started yet.
`public`	# `close( )` Ends the current session and store session data. Ends the current session and store session data.
`public`	# `destroy( )` Frees all session variables and destroys all data registered to a session. Frees all session variables and destroys all data registered to a session.
`public boolean`	# `getIsStarted( )` Returns `boolean` whether the session has started
`public string`	# `getSessionID( )` Returns `string` the current session ID
`public`	# `setSessionID( string $value )` Parameters `$value` `string` $value the session ID for the current session
`public`	# `regenerateID( boolean $deleteOldSession = false )` Updates the current session id with a newly generated one . Please refer to http://php.net/session_regenerate_id for more details. Updates the current session id with a newly generated one . Please refer to http://php.net/session_regenerate_id for more details. Parameters `$deleteOldSession` `boolean` $deleteOldSession Whether to delete the old associated session file or not. Since 1.1.8
`public string`	# `getSessionName( )` Returns `string` the current session name
`public`	# `setSessionName( string $value )` Parameters `$value` `string` $value the session name for the current session, must be an alphanumeric string, defaults to PHPSESSID
`public string`	# `getSavePath( )` Returns `string` the current session save path, defaults to http://php.net/session.save_path.
`public`	# `setSavePath( string $value )` Parameters `$value` `string` $value the current session save path Throws `CException` if the path is not a valid directory
`public array`	# `getCookieParams( )` Returns `array` the session cookie parameters. See http://us2.php.net/manual/en/function.session-get-cookie-params.php
`public`	# `setCookieParams( array $value )` 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. 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. Parameters `$value` `array` $value cookie parameters, valid keys include: lifetime, path, domain, secure, httponly. Note that httponly is all lowercase. See http://us2.php.net/manual/en/function.session-set-cookie-params.php
`public string`	# `getCookieMode( )` Returns `string` how to use cookie to store session ID. Defaults to 'Allow'.
`public`	# `setCookieMode( string $value )` Parameters `$value` `string` $value how to use cookie to store session ID. Valid values include 'none', 'allow' and 'only'.
`public float`	# `getGCProbability( )` Returns `float` the probability (percentage) that the gc (garbage collection) process is started on every session initialization, defaults to 1 meaning 1% chance.
`public`	# `setGCProbability( float $value )` Parameters `$value` `float` $value the probability (percentage) that the gc (garbage collection) process is started on every session initialization. Throws `CException` if the value is beyond [0,100]
`public boolean`	# `getUseTransparentSessionID( )` Returns `boolean` whether transparent sid support is enabled or not, defaults to false.
`public`	# `setUseTransparentSessionID( boolean $value )` Parameters `$value` `boolean` $value whether transparent sid support is enabled or not.
`public integer`	# `getTimeout( )` Returns `integer` the number of seconds after which data will be seen as 'garbage' and cleaned up, defaults to 1440 seconds.
`public`	# `setTimeout( integer $value )` Parameters `$value` `integer` $value the number of seconds after which data will be seen as 'garbage' and cleaned up
`public boolean`	# `openSession( string $savePath, string $sessionName )` Session open handler. This method should be overridden if useCustomStorage is set true. Do not call this method directly. Session open handler. This method should be overridden if useCustomStorage is set true. Do not call this method directly. Parameters `$savePath` `string` $savePath session save path `$sessionName` `string` $sessionName session name Returns `boolean` whether session is opened successfully
`public boolean`	# `closeSession( )` Session close handler. This method should be overridden if useCustomStorage is set true. Do not call this method directly. Session close handler. This method should be overridden if useCustomStorage is set true. Do not call this method directly. Returns `boolean` whether session is closed successfully
`public string`	# `readSession( string $id )` Session read handler. This method should be overridden if useCustomStorage is set true. Do not call this method directly. Session read handler. This method should be overridden if useCustomStorage is set true. Do not call this method directly. Parameters `$id` `string` $id session ID Returns `string` the session data
`public boolean`	# `writeSession( string $id, string $data )` Session write handler. This method should be overridden if useCustomStorage is set true. Do not call this method directly. Session write handler. This method should be overridden if useCustomStorage is set true. Do not call this method directly. Parameters `$id` `string` $id session ID `$data` `string` $data session data Returns `boolean` whether session write is successful
`public boolean`	# `destroySession( string $id )` Session destroy handler. This method should be overridden if useCustomStorage is set true. Do not call this method directly. Session destroy handler. This method should be overridden if useCustomStorage is set true. Do not call this method directly. Parameters `$id` `string` $id session ID Returns `boolean` whether session is destroyed successfully
`public boolean`	# `gcSession( integer $maxLifetime )` Session GC (garbage collection) handler. This method should be overridden if useCustomStorage is set true. Do not call this method directly. Session GC (garbage collection) handler. This method should be overridden if useCustomStorage is set true. Do not call this method directly. Parameters `$maxLifetime` `integer` $maxLifetime the number of seconds after which data will be seen as 'garbage' and cleaned up. Returns `boolean` whether session is GCed successfully
`public CHttpSessionIterator`	# `getIterator( )` Returns an iterator for traversing the session variables. This method is required by the interface IteratorAggregate. Returns an iterator for traversing the session variables. This method is required by the interface IteratorAggregate. Returns `CHttpSessionIterator` an iterator for traversing the session variables. Implementation of `IteratorAggregate::getIterator()`
`public integer`	# `getCount( )` Returns the number of items in the session. Returns the number of items in the session. Returns `integer` the number of session variables
`public integer`	# `count( )` Returns the number of items in the session. This method is required by Countable interface. Returns the number of items in the session. This method is required by Countable interface. Returns `integer` number of items in the session. Implementation of `Countable::count()`
`public array`	# `getKeys( )` Returns `array` the list of session variable names
`public mixed`	# `get( mixed $key, mixed $defaultValue = null )` Returns the session variable value with the session variable name. This method is very similar to `CHttpSession::itemAt()` and `CHttpSession::offsetGet()`, except that it will return $defaultValue if the session variable does not exist. Returns the session variable value with the session variable name. This method is very similar to `CHttpSession::itemAt()` and `CHttpSession::offsetGet()`, except that it will return $defaultValue if the session variable does not exist. Parameters `$key` `mixed` $key the session variable name `$defaultValue` `mixed` $defaultValue the default value to be returned when the session variable does not exist. Returns `mixed` the session variable value, or $defaultValue if the session variable does not exist. Since 1.1.2
`public mixed`	# `itemAt( mixed $key )` Returns the session variable value with the session variable name. This method is exactly the same as `CHttpSession::offsetGet()`. Returns the session variable value with the session variable name. This method is exactly the same as `CHttpSession::offsetGet()`. Parameters `$key` `mixed` $key the session variable name Returns `mixed` the session variable value, null if no such variable exists
`public`	# `add( mixed $key, mixed $value )` Adds a session variable. Note, if the specified name already exists, the old value will be removed first. Adds a session variable. Note, if the specified name already exists, the old value will be removed first. Parameters `$key` `mixed` $key session variable name `$value` `mixed` $value session variable value
`public mixed`	# `remove( mixed $key )` Removes a session variable. Removes a session variable. Parameters `$key` `mixed` $key the name of the session variable to be removed Returns `mixed` the removed value, null if no such session variable.
`public`	# `clear( )` Removes all session variables Removes all session variables
`public boolean`	# `contains( mixed $key )` Parameters `$key` `mixed` $key session variable name Returns `boolean` whether there is the named session variable
`public array`	# `toArray( )` Returns `array` the list of all session variables in array
`public boolean`	# `offsetExists( mixed $offset )` This method is required by the interface ArrayAccess. This method is required by the interface ArrayAccess. Parameters `$offset` `mixed` $offset the offset to check on Returns `boolean` Implementation of `ArrayAccess::offsetExists()`
`public mixed`	# `offsetGet( integer $offset )` This method is required by the interface ArrayAccess. This method is required by the interface ArrayAccess. Parameters `$offset` `integer` $offset the offset to retrieve element. Returns `mixed` the element at the offset, null if no element is found at the offset Implementation of `ArrayAccess::offsetGet()`
`public`	# `offsetSet( integer $offset, mixed $item )` This method is required by the interface ArrayAccess. This method is required by the interface ArrayAccess. Parameters `$offset` `integer` $offset the offset to set element `$item` `mixed` $item the element value Implementation of `ArrayAccess::offsetSet()`
`public`	# `offsetUnset( mixed $offset )` This method is required by the interface ArrayAccess. This method is required by the interface ArrayAccess. Parameters `$offset` `mixed` $offset the offset to unset element Implementation of `ArrayAccess::offsetUnset()`

Methods inherited from CApplicationComponent
`getIsInitialized()`

Methods inherited from CComponent
`__call(), __get(), __isset(), __set(), __unset(), asa(), attachBehavior(), attachBehaviors(), attachEventHandler(), canGetProperty(), canSetProperty(), detachBehavior(), detachBehaviors(), detachEventHandler(), disableBehavior(), disableBehaviors(), enableBehavior(), enableBehaviors(), evaluateExpression(), getEventHandlers(), hasEvent(), hasEventHandler(), hasProperty(), raiseEvent()`

Properties summary
`public boolean`	`$autoStart`	`true`	# whether the session should be automatically started when the session application component is initialized, defaults to true. whether the session should be automatically started when the session application component is initialized, defaults to true.

Properties inherited from CApplicationComponent
`$behaviors`

Magic properties summary
`public boolean`	`$useCustomStorage`	# Whether to use custom storage. Whether to use custom storage.
`public boolean`	`$isStarted`	# Whether the session has started. Whether the session has started.
`public string`	`$sessionID`	# The current session ID. The current session ID.
`public string`	`$sessionName`	# The current session name. The current session name.
`public string`	`$savePath`	# The current session save path, defaults to http://php.net/session.save_path. The current session save path, defaults to http://php.net/session.save_path.
`public array`	`$cookieParams`	# The session cookie parameters. The session cookie parameters.
`public string`	`$cookieMode`	# How to use cookie to store session ID. Defaults to 'Allow'. How to use cookie to store session ID. Defaults to 'Allow'.
`public float`	`$gCProbability`	# The probability (percentage) that the gc (garbage collection) process is started on every session initialization, defaults to 1 meaning 1% chance. The probability (percentage) that the gc (garbage collection) process is started on every session initialization, defaults to 1 meaning 1% chance.
`public boolean`	`$useTransparentSessionID`	# Whether transparent sid support is enabled or not, defaults to false. Whether transparent sid support is enabled or not, defaults to false.
`public integer`	`$timeout`	# The number of seconds after which data will be seen as 'garbage' and cleaned up, defaults to 1440 seconds. The number of seconds after which data will be seen as 'garbage' and cleaned up, defaults to 1440 seconds.
`public CHttpSessionIterator`	`$iterator`	# An iterator for traversing the session variables. An iterator for traversing the session variables.
`public integer`	`$count`	# The number of session variables. The number of session variables.
`public array`	`$keys`	# The list of session variable names. The list of session variable names.

Magic properties inherited from CApplicationComponent
`$isInitialized`

Packages

Classes

Interfaces

Class CHttpSession

Direct known subclasses

Overrides

Returns

Returns

Returns

Parameters

Parameters

Since

Returns

Parameters

Returns

Parameters

Throws

Returns

See

Parameters

See

Returns

Parameters

Returns

Parameters

Throws

Returns

Parameters

Returns

Parameters

Parameters

Returns

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Returns

Implementation of

Returns

Returns

Implementation of

Returns

Parameters

Returns

Since

Parameters

Returns

Parameters

Parameters

Returns

Parameters

Returns

Returns

Parameters

Returns

Implementation of

Parameters

Returns

Implementation of

Parameters

Implementation of

Parameters

Implementation of