Packages:
default
System
System.Caching
System.Collections
System.Data
System.Data.ActiveRecord
System.Data.ActiveRecord.Relations
System.Data.ActiveRecord.Scaffold
System.Data.ActiveReecord.Scaffold.InputBuilder
System.Data.Commom.Sqlite
System.Data.Common
System.Data.Common.Mssql
System.Data.Common.Mysql
System.Data.Common.Oracle
System.Data.Common.Pgsql
System.Data.Common.Sqlite
System.Data.DataGateway
System.Data.SqlMap
System.Data.SqlMap.Configuration
System.Data.SqlMap.Statements
System.Exceptions
System.I18N
System.IO
System.Security
System.Util
System.Web
System.Web.Services
System.Web.UI
System.Web.UI.ActiveControls
System.Web.UI.WebControls
System.Web.UI.WebControls.assets
System.Xml


Classes:
Keyword

Class THttpSession

TComponent
   |
   --TApplicationComponent
      |
      --THttpSession

Direct Known Sub-classes:

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,

  1. $session=new THttpSession;
  2. $session->open();
  3. $value1=$session['name1']; // get session variable 'name1'
  4. $value2=$session['name2']; // get session variable 'name2'
  5. foreach($session as $name=>$value) // traverse all session variables
  6. $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,

  1. <module id="session" class="THttpSession" SessionName="SSID" SavePath="/tmp"
  2. CookieMode="Allow" UseCustomStorage="false" AutoStart="true" GCProbability="1"
  3. UseTransparentSessionID="true" TimeOut="3600" />
where SessionName, SavePath, CookieMode, UseCustomStorage, AutoStart, GCProbability, UseTransparentSessionID and getTimeOut are configurable properties of THttpSession.

Since: 3.0
Author: Qiang Xue <qiang.xue@gmail.com>

Method Summary
void
add ( mixed $key, mixed $value)
Adds a session variable.
void
clear ()
Removes all session variables
void
close ()
Ends the current session and store session data.
boolean
contains ( mixed $key)
integer
count ()
Returns the number of items in the session.
void
destroy ()
Destroys all data registered to a session.
boolean
THttpCookie
THttpSessionCookieMode
integer
integer
string
getID ()
boolean
TSessionIterator
Returns an iterator for traversing the session variables.
array
getKeys ()
string
string
string
integer
boolean
boolean
void
init ( TXmlElement $config)
Initializes the module.
mixed
itemAt ( mixed $key)
Returns the session variable value with the session variable name.
boolean
offsetExists ( mixed $offset)
This method is required by the interface ArrayAccess.
mixed
offsetGet ( integer $offset)
This method is required by the interface ArrayAccess.
void
offsetSet ( integer $offset, mixed $item)
This method is required by the interface ArrayAccess.
void
offsetUnset ( mixed $offset)
This method is required by the interface ArrayAccess.
void
open ()
Starts the session if it has not started yet.
mixed
remove ( mixed $key)
Removes a session variable.
void
setAutoStart ( boolean $value)
void
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 ()
Session close handler.
boolean
_destroy ( string $id)
Session destroy handler.
boolean
_gc ( integer $maxLifetime)
Session GC (garbage collection) handler.
boolean
_open ( string $savePath, string $sessionName)
Session open handler.
string
_read ( string $id)
Session read handler.
boolean
_write ( string $id, string $data)
Session write handler.
Methods Inherited From TApplicationComponent
TApplicationComponent::getApplication(), TApplicationComponent::getRequest(), TApplicationComponent::getResponse(), TApplicationComponent::getService(), TApplicationComponent::getSession(), TApplicationComponent::getUser(), TApplicationComponent::publishAsset(), TApplicationComponent::publishFilePath()
Methods Inherited From TComponent
TComponent::addParsedObject(), TComponent::attachEventHandler(), TComponent::canGetProperty(), TComponent::canSetProperty(), TComponent::createdOnTemplate(), TComponent::detachEventHandler(), TComponent::evaluateExpression(), TComponent::evaluateStatements(), TComponent::getEventHandlers(), TComponent::getSubProperty(), TComponent::hasEvent(), TComponent::hasEventHandler(), TComponent::hasProperty(), TComponent::raiseEvent(), TComponent::setSubProperty(), TComponent::__get(), TComponent::__set()

Method Details

add

public void add (mixed $key , mixed $value )

Adds a session variable.

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

Input
mixed$keysession variable name
mixed$valuesession variable value
Output
Exception

clear

public void clear ()

Removes all session variables

Output
Exception

close

public void close ()

Ends the current session and store session data.

Output
Exception

contains

public boolean contains (mixed $key )

Input
mixed$keysession variable name
Output
boolean whether there is the named session variable
Exception

count

public integer count ()

Returns the number of items in the session.

This method is required by Countable interface.

Output
integer number of items in the session.
Exception

destroy

public void destroy ()

Destroys all data registered to a session.

Output
Exception

getAutoStart

public boolean getAutoStart ()

Output
boolean whether the session should be automatically started when the session module is initialized, defaults to false.
Exception

getCookie

public THttpCookie getCookie ()

Output
THttpCookie cookie that will be used to store session ID
Exception

getCookieMode

public THttpSessionCookieMode getCookieMode ()

Output
THttpSessionCookieMode how to use cookie to store session ID. Defaults to THttpSessionCookieMode::Allow.
Exception

getCount

public integer getCount ()

Output
integer the number of session variables
Exception

getGCProbability

public integer getGCProbability ()

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

getID

public string getID ()

Output
string id of this module
Exception

getIsStarted

public boolean getIsStarted ()

Output
boolean whether the session has started
Exception

getIterator

public TSessionIterator getIterator ()

Returns an iterator for traversing the session variables.

This method is required by the interface IteratorAggregate.

Output
TSessionIterator an iterator for traversing the session variables.
Exception

getKeys

public array getKeys ()

Output
array the list of session variable names
Exception

getSavePath

public string getSavePath ()

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

getSessionID

public string getSessionID ()

Output
string the current session ID
Exception

getSessionName

public string getSessionName ()

Output
string the current session name
Exception

getTimeout

public integer getTimeout ()

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

getUseCustomStorage

public boolean getUseCustomStorage ()

Output
boolean whether to use user-specified handlers to store session data. Defaults to false.
Exception

getUseTransparentSessionID

public boolean getUseTransparentSessionID ()

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

init

public void init (TXmlElement $config )

Initializes the module.

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

Input
TXmlElement$configmodule configuration
Output
Exception

itemAt

public mixed itemAt (mixed $key )

Returns the session variable value with the session variable name.

This method is exactly the same as offsetGet.

Input
mixed$keythe session variable name
Output
mixed the session variable value, null if no such variable exists
Exception

offsetExists

public boolean offsetExists (mixed $offset )

This method is required by the interface ArrayAccess.

Input
mixed$offsetthe offset to check on
Output
Exception

offsetGet

public mixed offsetGet (integer $offset )

This method is required by the interface ArrayAccess.

Input
integer$offsetthe offset to retrieve element.
Output
mixed the element at the offset, null if no element is found at the offset
Exception

offsetSet

public void offsetSet (integer $offset , mixed $item )

This method is required by the interface ArrayAccess.

Input
integer$offsetthe offset to set element
mixed$itemthe element value
Output
Exception

offsetUnset

public void offsetUnset (mixed $offset )

This method is required by the interface ArrayAccess.

Input
mixed$offsetthe offset to unset element
Output
Exception

open

public void open ()

Starts the session if it has not started yet.

Output
Exception

remove

public mixed remove (mixed $key )

Removes a session variable.

Input
mixed$keythe name of the session variable to be removed
Output
mixed the removed value, null if no such session variable.
Exception

setAutoStart

public void setAutoStart (boolean $value )

Input
boolean$valuewhether the session should be automatically started when the session module is initialized, defaults to false.
Output
Exception
throwsTInvalidOperationException if session is started already

setCookieMode

public void setCookieMode (THttpSessionCookieMode $value )

Input
THttpSessionCookieMode$valuehow to use cookie to store session ID
Output
Exception
throwsTInvalidOperationException if session is started already

setGCProbability

public void setGCProbability (integer $value )

Input
integer$valuethe probability (percentage) that the gc (garbage collection) process is started on every session initialization.
Output
Exception
throwsTInvalidOperationException if session is started already
throwsTInvalidDataValueException if the value is beyond [0,100].

setID

public void setID (string $value )

Input
string$valueid of this module
Output
Exception

setSavePath

public void setSavePath (string $value )

Input
string$valuethe current session save path
Output
Exception
throwsTInvalidOperationException if session is started already

setSessionID

public void setSessionID (string $value )

Input
string$valuethe session ID for the current session
Output
Exception
throwsTInvalidOperationException if session is started already

setSessionName

public void setSessionName (string $value )

Input
string$valuethe session name for the current session, must be an alphanumeric string, defaults to PHPSESSID
Output
Exception
throwsTInvalidOperationException if session is started already

setTimeout

public void setTimeout (integer $value )

Input
integer$valuethe number of seconds after which data will be seen as 'garbage' and cleaned up
Output
Exception
throwsTInvalidOperationException if session is started already

setUseCustomStorage

public void setUseCustomStorage (boolean $value )

Input
boolean$valuewhether 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.
Output
Exception

setUseTransparentSessionID

public void setUseTransparentSessionID (boolean $value )

Input
boolean$valuewhether transparent sid support is enabled or not.
Output
Exception

toArray

public array toArray ()

Output
array the list of all session variables in array
Exception

_close

public boolean _close ()

Session close handler.

This method should be overridden if UseCustomStorage is set true.

Output
boolean whether session is closed successfully
Exception

_destroy

public boolean _destroy (string $id )

Session destroy handler.

This method should be overridden if UseCustomStorage is set true.

Input
string$idsession ID
Output
boolean whether session is destroyed successfully
Exception

_gc

public boolean _gc (integer $maxLifetime )

Session GC (garbage collection) handler.

This method should be overridden if UseCustomStorage is set true.

Input
integer$maxLifetimethe number of seconds after which data will be seen as 'garbage' and cleaned up.
Output
boolean whether session is GCed successfully
Exception

_open

public boolean _open (string $savePath , string $sessionName )

Session open handler.

This method should be overridden if UseCustomStorage is set true.

Input
string$savePathsession save path
string$sessionNamesession name
Output
boolean whether session is opened successfully
Exception

_read

public string _read (string $id )

Session read handler.

This method should be overridden if UseCustomStorage is set true.

Input
string$idsession ID
Output
string the session data
Exception

_write

public boolean _write (string $id , string $data )

Session write handler.

This method should be overridden if UseCustomStorage is set true.

Input
string$idsession ID
string$datasession data
Output
boolean whether session write is successful
Exception