- Home
- About
- Testimonials
- Demos
- Download
- Documentation
- Blogs
- Forum
- Support

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:
TAssetManager
TCacheHttpSession
THttpCookie
THttpCookieCollection
THttpRequest
THttpRequestUrlFormat
THttpResponse
THttpResponseAdapter
THttpSession
THttpSessionCookieMode
THttpUtility
TSessionIterator
TUri
TUrlManager
TUrlMapping
TUrlMappingPattern

Keyword

# Class THttpSession

    TComponent
       |
       --TApplicationComponent
          |
          --THttpSession

#### Direct Known Sub-classes:

TCacheHttpSession

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
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 | getAutoStart ()
THttpCookie | getCookie ()
THttpSessionCookieMode | getCookieMode ()
integer | getCount ()
integer | getGCProbability ()
string | getID ()
boolean | getIsStarted ()
TSessionIterator | getIterator () Returns an iterator for traversing the session variables.
array | getKeys ()
string | getSavePath ()
string | getSessionID ()
string | getSessionName ()
integer | getTimeout ()
boolean | getUseCustomStorage ()
boolean | getUseTransparentSessionID ()
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 | setCookieMode ( THttpSessionCookieMode $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 () 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 | $key | session variable name
mixed | $value | session 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 | $key | session 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 | $config | module 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 | $key | the 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 | $offset | the offset to check on
Output
Exception

## offsetGet

public mixed offsetGet | (integer $offset )

This method is required by the interface ArrayAccess.

Input
integer | $offset | the 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 | $offset | the offset to set element
mixed | $item | the element value
Output
Exception

## offsetUnset

public void offsetUnset | (mixed $offset )

This method is required by the interface ArrayAccess.

Input
mixed | $offset | the 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 | $key | the 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 | $value | whether the session should be automatically started when the session module is initialized, defaults to false.
Output
Exception
throws | TInvalidOperationException if session is started already

## setCookieMode

public void setCookieMode | (THttpSessionCookieMode $value )

Input
THttpSessionCookieMode | $value | how to use cookie to store session ID
Output
Exception
throws | TInvalidOperationException if session is started already

## setGCProbability

public void setGCProbability | (integer $value )

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

## setID

public void setID | (string $value )

Input
string | $value | id of this module
Output
Exception

## setSavePath

public void setSavePath | (string $value )

Input
string | $value | the current session save path
Output
Exception
throws | TInvalidOperationException if session is started already

## setSessionID

public void setSessionID | (string $value )

Input
string | $value | the session ID for the current session
Output
Exception
throws | TInvalidOperationException if session is started already

## setSessionName

public void setSessionName | (string $value )

Input
string | $value | the session name for the current session, must be an alphanumeric string, defaults to PHPSESSID
Output
Exception
throws | TInvalidOperationException if session is started already

## setTimeout

public void setTimeout | (integer $value )

Input
integer | $value | the number of seconds after which data will be seen as 'garbage' and cleaned up
Output
Exception
throws | TInvalidOperationException if session is started already

## setUseCustomStorage

public void setUseCustomStorage | (boolean $value )

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

## setUseTransparentSessionID

public void setUseTransparentSessionID | (boolean $value )

Input
boolean | $value | whether 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 | $id | session 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 | $maxLifetime | the 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 | $savePath | session save path
string | $sessionName | session 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 | $id | session 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 | $id | session ID
string | $data | session data
Output
boolean | whether session write is successful
Exception