## Class THttpSession

Description

Implements interfaces:

- IModule

THttpSession class

THttpSession 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 true, then the session will be started once the session module is loaded and initialized.

To access data stored in session, use THttpSession like an associative array. For example,

       $session=new THttpSession;
       $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: AutoStart, setCookie, setCacheLimiter, SavePath, UseCustomStorage, GCProbability, setCookieUsage, Timeout. See the corresponding setter and getter documentation for more information. Note, these properties must be set before the session is started.

THttpSession can be inherited with customized session storage method. Override _open, _close, _read, _write, _destroy and _gc and set UseCustomStorage to true. Then, the session data will be stored using the above methods.

By default, THttpSession is registered with TApplication as the request module. It can be accessed via TApplication::getSession().

THttpSession may be configured in application configuration file as follows, <module id="session" class="THttpSession" SessionName="SSID" SavePath="/tmp" CookieMode="Allow" UseCustomStorage="false" AutoStart="true" GCProbability="1" UseTransparentSessionID="true" TimeOut="3600" /> where SessionName, SavePath, CookieMode, UseCustomStorage, AutoStart, GCProbability, UseTransparentSessionID and getTimeOut are configurable properties of THttpSession.

- since: 3.0
- version: $Revision: $ $Date: $
- author: Qiang Xue <qiang.xue@gmail.com>

Located in /Web/THttpSession.php (line 62)

    TComponent
       |
       --TApplicationComponent
          |
          --THttpSession

Method Summary
void __destruct ()
void add (mixed $key, mixed $value)
void clear ()
void close ()
boolean contains (mixed $key)
void destroy ()
boolean getAutoStart ()
THttpCookie getCookie ()
string getCookieMode ()
integer getCount ()
integer getGCProbability ()
string getID ()
boolean getIsStarted ()
TSessionIterator getIterator ()
array getKeys ()
string getSavePath ()
string getSessionID ()
string getSessionName ()
integer getTimeout ()
boolean getUseCustomStorage ()
boolean getUseTransparentSessionID ()
void init (TXmlElement $config)
mixed itemAt (mixed $key)
boolean offsetExists (mixed $offset)
mixed offsetGet (integer $offset)
void offsetSet (integer $offset, mixed $item)
void offsetUnset (mixed $offset)
void open ()
mixed remove (mixed $key)
void setAutoStart (boolean $value)
void setCookieMode (string $value)
void setGCProbability (integer $value)
void setID (string $value)
void setSavePath (string $value)
void setSessionID (string $value)
void setSessionName (string $value)
void setTimeout (integer $value)
void setUseCustomStorage (boolean $value)
void setUseTransparentSessionID (boolean $value)
array toArray ()
boolean _close ()
boolean _destroy (string $id)
boolean _gc (integer $maxLifetime)
boolean _open (string $savePath, string $sessionName)
string _read (string $id)
boolean _write (string $id, string $data)
Methods
Destructor __destruct (line 93)

Destructor.

Closes session.

- access: public

void __destruct ()
add (line 512)

Adds a session variable.

Note, if the specified name already exists, the old value will be removed first.

- access: public

void add (mixed $key, mixed $value)

- mixed $key: session variable name
- mixed $value: session variable value

clear (line 537)

Removes all session variables

- access: public

void clear ()
close (line 148)

Ends the current session and store session data.

- access: public

void close ()
contains (line 547)

- return: whether there is the named session variable
- access: public

boolean contains (mixed $key)

- mixed $key: session variable name

destroy (line 160)

Destroys all data registered to a session.

- access: public

void destroy ()
getAutoStart (line 314)

- return: whether the session should be automatically started when the session module is initialized, defaults to false.
- access: public

boolean getAutoStart ()
getCookie (line 263)

- return: cookie that will be used to store session ID
- access: public

THttpCookie getCookie ()
getCookieMode (line 274)

- return: (None|Allow|Only) how to use cookie to store session ID 'None' means not using cookie, 'Allow' means using cookie, and 'Only' means using cookie only, defaults to 'Allow'.
- access: public

string getCookieMode ()
getCount (line 482)

- return: the number of session variables
- access: public

integer getCount ()
getGCProbability (line 334)

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

integer getGCProbability ()
getID (line 102)

- return: id of this module
- access: public

string getID ()
getIsStarted (line 172)

- return: whether the session has started
- access: public

boolean getIsStarted ()
getIterator (line 474)

Returns an iterator for traversing the session variables.

This method is required by the interface IteratorAggregate.

- return: an iterator for traversing the session variables.
- access: public

TSessionIterator getIterator ()
getKeys (line 490)

- return: the list of session variable names
- access: public

array getKeys ()
getSavePath (line 222)

- return: the current session save path, defaults to '/tmp'.
- access: public

string getSavePath ()
getSessionID (line 180)

- return: the current session ID
- access: public

string getSessionID ()
getSessionName (line 200)

- return: the current session name
- access: public

string getSessionName ()
getTimeout (line 383)

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

integer getTimeout ()
getUseCustomStorage (line 244)

- return: whether to use user-specified handlers to store session data. Defaults to false.
- access: public

boolean getUseCustomStorage ()
getUseTransparentSessionID (line 364)

- return: whether transparent sid support is enabled or not, defaults to false.
- access: public

boolean getUseTransparentSessionID ()
init (line 121)

Initializes the module.

This method is required by IModule. If AutoStart is true, the session will be started.

- access: public

void init (TXmlElement $config)

- TXmlElement $config: module configuration

itemAt (line 501)

Returns the session variable value with the session variable name.

This method is exactly the same as offsetGet.

- return: the session variable value, null if no such variable exists
- access: public

mixed itemAt (mixed $key)

- mixed $key: the session variable name

offsetExists (line 565)

This method is required by the interface ArrayAccess.

- access: public

boolean offsetExists (mixed $offset)

- mixed $offset: the offset to check on

offsetGet (line 575)

This method is required by the interface ArrayAccess.

- return: the element at the offset, null if no element is found at the offset
- access: public

mixed offsetGet (integer $offset)

- integer $offset: the offset to retrieve element.

offsetSet (line 585)

This method is required by the interface ArrayAccess.

- access: public

void offsetSet (integer $offset, mixed $item)

- integer $offset: the offset to set element
- mixed $item: the element value

offsetUnset (line 594)

This method is required by the interface ArrayAccess.

- access: public

void offsetUnset (mixed $offset)

- mixed $offset: the offset to unset element

open (line 132)

Starts the session if it has not started yet.

- access: public

void open ()
remove (line 522)

Removes a session variable.

- return: the removed value, null if no such session variable.
- access: public

mixed remove (mixed $key)

- mixed $key: the name of the session variable to be removed

setAutoStart (line 323)

- access: public
- throws: TInvalidOperationException if session is started already

void setAutoStart (boolean $value)

- boolean $value: whether the session should be automatically started when the session module is initialized, defaults to false.

setCookieMode (line 289)

- access: public
- throws: TInvalidOperationException if session is started already

void setCookieMode (string $value)

- string $value: (None|Allow|Only) how to use cookie to store session ID 'None' means not using cookie, 'Allow' means using cookie, and 'Only' means using cookie only.

setGCProbability (line 344)

- access: public
- throws: TInvalidOperationException if session is started already
- throws: TInvalidDataValueException if the value is beyond [0,100].

void setGCProbability (integer $value)

- integer $value: the probability (percentage) that the gc (garbage collection) process is started on every session initialization.

setID (line 110)

- access: public

void setID (string $value)

- string $value: id of this module

setSavePath (line 231)

- access: public
- throws: TInvalidOperationException if session is started already

void setSavePath (string $value)

- string $value: the current session save path

setSessionID (line 189)

- access: public
- throws: TInvalidOperationException if session is started already

void setSessionID (string $value)

- string $value: the session ID for the current session

setSessionName (line 209)

- access: public
- throws: TInvalidOperationException if session is started already

void setSessionName (string $value)

- string $value: the session name for the current session, must be an alphanumeric string, defaults to PHPSESSID

setTimeout (line 392)

- access: public
- throws: TInvalidOperationException if session is started already

void setTimeout (integer $value)

- integer $value: the number of seconds after which data will be seen as 'garbage' and cleaned up

setUseCustomStorage (line 255)

- access: public

void setUseCustomStorage (boolean $value)

- boolean $value: whether to use user-specified handlers to store session data. If true, make sure the methods _open, _close, _read, _write, _destroy, and _gc are overridden in child class, because they will be used as the callback handlers.

setUseTransparentSessionID (line 372)

- access: public

void setUseTransparentSessionID (boolean $value)

- boolean $value: whether transparent sid support is enabled or not.

toArray (line 555)

- return: the list of all session variables in array
- access: public

array toArray ()
_close (line 417)

Session close handler.

This method should be overriden if session Storage is set as 'user'.

- return: whether session is closed successfully
- access: public

boolean _close ()
_destroy (line 451)

Session destroy handler.

This method should be overriden if session Storage is set as 'user'.

- return: whether session is destroyed successfully
- access: public

boolean _destroy (string $id)

- string $id: session ID

_gc (line 462)

Session GC (garbage collection) handler.

This method should be overriden if session Storage is set as 'user'.

- return: whether session is GCed successfully
- access: public

boolean _gc (integer $maxLifetime)

- integer $maxLifetime: the number of seconds after which data will be seen as 'garbage' and cleaned up.

_open (line 407)

Session open handler.

This method should be overriden if session Storage is set as 'user'.

- return: whether session is opened successfully
- access: public

boolean _open (string $savePath, string $sessionName)

- string $savePath: session save path
- string $sessionName: session name

_read (line 428)

Session read handler.

This method should be overriden if session Storage is set as 'user'.

- return: the session data
- access: public

string _read (string $id)

- string $id: session ID

_write (line 440)

Session write handler.

This method should be overriden if session Storage is set as 'user'.

- return: whether session write is successful
- access: public

boolean _write (string $id, string $data)

- string $id: session ID
- string $data: session data

#### Inherited Methods

Inherited From TApplicationComponent

> TApplicationComponent::getApplication()
> TApplicationComponent::getRequest()
> TApplicationComponent::getResponse()
> TApplicationComponent::getService()
> TApplicationComponent::getSession()
> TApplicationComponent::getUser()
> TApplicationComponent::publishAsset()
> TApplicationComponent::publishFilePath()

Inherited From TComponent

> TComponent::attachEventHandler()
> TComponent::canGetProperty()
> TComponent::canSetProperty()
> TComponent::detachEventHandler()
> TComponent::evaluateExpression()
> TComponent::evaluateStatements()
> TComponent::getEventHandlers()
> TComponent::getSubProperty()
> TComponent::hasEvent()
> TComponent::hasEventHandler()
> TComponent::hasProperty()
> TComponent::raiseEvent()
> TComponent::setSubProperty()
> TComponent::__get()
> TComponent::__set()

Documentation generated on Mon, 01 May 2006 23:03:41 -0400 by phpDocumentor 1.3.0RC4