Session handling

From Cloudrexx Development Wiki
Jump to: navigation, search

Cloudrexx has its own session handler in order to be independent from server configuration.

In backend mode, session is initialized automaticly, but in frontend, the session must be initialized explicitly.

Note: This documentation refers to version 5 or newer. For older versions of Cloudrexx, please refer to Session handling pre 3.2 or Session handling 3.2.


Initialization

To initialize a session, do as follows:

$session = $this->cx->getComponent('Session')->getSession();

This will either initialize a new session or resume an existing one (in case the request did supply a valid session ID).

Resume existing session

To resume an existing session, but not to initialize a new session, do as follows:

// note: in case no existing session exists, $session will be set to NULL
// otherwise it will contain an instance of \Cx\Core\Session\Model\Entity\Session
$session = $this->cx->getComponent('Session')->getSession(false);

Checking whether the session is initialized

To check if a session has been initialized, do as follows:

if ($this->cx->getComponent('Session')->isInitialized()) }
    \DBG::log('Session has been initialized');
}

Close session

To close an initialized session, do as follows:

// fetch existing session (but do not initialize a new one)
$session = $this->cx->getComponent('Session')->getSession(false);
if ($session) {
    // close the current session
    // important: this will not delete the session - just close it
    $session->destroy();
}

Delete session

To delete an existing session, do as follows:

// fetch existing session (but do not initialize a new one)
$session = $this->cx->getComponent('Session')->getSession();
if ($session) {
    // permanently delete all data of the current session
    $session->destroy($session->getIdOfActiveSession());
}

Delete all sessions of a particular user

To delete all sessions of a particular user, do as follows:

$session = $this->cx->getComponent('Session')->getSession();
$session->cmsSessionDestroyByUserId($userId);
Note: This currently only works if the call is made from within an existing session.

Fetch session data

// ensure session is initialized
$this->cx->getComponent('Session')->getSession();
// scalar values can be accessed directly:
$var = $_SESSION['scalar_value'];

// multidimensional arrays must be fetch through the helper <code>toArray()</code>:
$array = $_SESSION['any_key_to_array_data']->toArray();

Use temporary session storage

Each session provides a temporary storage location that will be flushed automatically once the session expires. Assess as follows:

$session = $this->cx->getComponent('Session')->getSession();
// fetch absolute storage location path
$path = $session->getTempPath();

// fetch relative storage location path (to be used for accessing through HTTP)
$path = $session->getWebTempPath();

Technical Information

Session ID

The session ID has the following format:

[a-v0-9]{32}

Storage

All session data is stored in the database in the following tables:

  • contrexx_sessions
  • contrexx_session_variable

Session Data

Session data is accessible through the pseudo-array $_SESSION, which (in contrary to native PHP where the superglobal is a variable of type array) is an instance of \Cx\Core\Model\RecursiveArrayAccess. \Cx\Core\Model\RecursiveArrayAccess allows us to track in depth which part of the session data has been altered and must be flushed to the database. Without this, we would need to flush the whole session to the database afer each processed request, which would vastly slow done the system.

Important: The length of keys is limited to 100 characters.