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.
Method Summary |
void
|
add
( mixed $key, mixed $value)
Adds a session variable.
|
void
|
Removes all session variables
|
void
|
Ends the current session and store session data.
|
boolean
|
|
integer
|
Returns the number of items in the session.
|
void
|
Destroys all data registered to a session.
|
boolean
|
|
THttpCookie
|
|
THttpSessionCookieMode
|
|
integer
|
|
integer
|
|
string
|
|
boolean
|
|
TSessionIterator
|
Returns an iterator for traversing the session variables.
|
array
|
|
string
|
|
string
|
|
string
|
|
integer
|
|
boolean
|
|
boolean
|
|
void
|
Initializes the module.
|
mixed
|
Returns the session variable value with the session variable name.
|
boolean
|
This method is required by the interface ArrayAccess.
|
mixed
|
This method is required by the interface ArrayAccess.
|
void
|
This method is required by the interface ArrayAccess.
|
void
|
This method is required by the interface ArrayAccess.
|
void
|
Starts the session if it has not started yet.
|
mixed
|
Removes a session variable.
|
void
|
|
void
|
|
void
|
|
void
|
|
void
|
|
void
|
|
void
|
|
void
|
|
void
|
|
void
|
|
array
|
|
boolean
|
Session close handler.
|
boolean
|
Session destroy handler.
|
boolean
|
_gc
( integer $maxLifetime)
Session GC (garbage collection) handler.
|
boolean
|
_open
( string $savePath, string $sessionName)
Session open handler.
|
string
|
Session read handler.
|
boolean
|
_write
( string $id, string $data)
Session write handler.
|
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
Removes all session variables
|
close
Ends the current session and store session data.
|
contains
public boolean contains |
(mixed $key ) |
Input |
mixed | $key | session variable name |
Output |
boolean
| whether there is the named session variable |
Exception |
|
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
Destroys all data registered to a session.
|
getAutoStart
public boolean getAutoStart |
() |
Output |
boolean
| whether the session should be automatically started when the session module is initialized, defaults to false. |
Exception |
|
getCookie
Output |
THttpCookie
| cookie that will be used to store session ID |
Exception |
|
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
Output |
string
| id of this module |
Exception |
|
getIsStarted
public boolean getIsStarted |
() |
Output |
boolean
| whether the session has started |
Exception |
|
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
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
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
Starts the session if it has not started yet.
|
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
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
Output |
array
| the list of all session variables in array |
Exception |
|
_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 |
|