Session

A session holds a small amount of data for one visitor across several requests: who they are logged in as, the form token that guards their writes, the filters they left a list screen on. The Session facade resolves Hubzero\Session\Manager, which wraps PHP's session with a namespace scheme and a token.

Reach for it only for something that belongs to this visitor, is small, and does not matter if it is lost. A half-finished booking a member is stepping through, a flag saying they have dismissed a notice, the sort order they chose. Anything a member would be annoyed to lose belongs in a table, and anything expensive to compute but the same for everyone belongs in the cache.

The manager is registered by SessionServiceProvider in the site and administrator applications only. The storage handler comes from session_handler in app/config/session.php — database (the default on a hub), file, memcache, memcached, redis, apc, xcache or none — and the lifetime from lifetime, which is in minutes and is multiplied out to seconds when the manager is built.

Storing and reading

use Session;

Session::set('bookings.wizard.instrument', $id, 'com_bookings');

$id = Session::get('bookings.wizard.instrument', 0, 'com_bookings');

Method	Signature
get	get($name, $default = null, $namespace = 'default')
set	set($name, $value = null, $namespace = 'default') — returns the previous value
has	has($name, $namespace = 'default')
clear	clear($name, $namespace = 'default') — removes it and returns what it held

The namespace is the third argument, not the second, and it keeps two extensions from colliding over a common name. It is stored prefixed with __, so default becomes $_SESSION['__default'].

Session::set('cart', $cart, 'com_cart');

$cart = Session::get('cart', array(), 'com_cart');

Get the argument order wrong — Session::get('cart', 'com_cart') — and you have asked for cart in the default namespace with the string 'com_cart' as its default. It compiles, it runs, and it returns 'com_cart'. Nothing anywhere reports it.

get() and has() return early when the session is not active, so a value read outside a live session comes back as the default rather than raising.

The form token

Every request that changes something must carry a token, and the check is one line at the top of the task:

// Throws a 403 if the token is missing or wrong
Request::checkToken();

Request::checkToken($method = 'post') delegates to Session::checkToken(), which looks for a request variable whose name is the token and whose value is anything truthy. $method may be 'post', 'get', or a comma-separated list. Pass true as the second argument to Session::checkToken() to get false back instead of an aborted request.

For a form, emit the hidden field with Html::input('token'). For a link that performs an action, append the token by hand:

$url = Route::url('index.php?option=com_blog&task=publish&id=' . $row->get('id')
    . '&' . Session::getFormToken() . '=1');

Method	What it does
getToken($forceNew = false)	The raw session token, created on first use
getFormToken($forceNew = false)	App::hash(user id . token) — the name to use in a form or URL
hasToken($tCheck, $forceExpire = true)	Compare a token; expires the session on a mismatch
checkToken($method = 'post', $capture = false)	Static. Aborts with 403 unless a valid token is present

getFormToken() mixes in the user id, so the token a guest sees and the token that member sees after logging in are different values.

The session's own state

Method	Returns
getId()	The session id
getName()	The cookie name — a hash of the hub secret and the client
getState()	active, expired, destroyed, error
getExpire()	The lifetime in seconds
isNew()	Whether this request created the session
restart() / fork() / reregister()	Start over, or move the data to a fresh id
destroy()	Discard everything
close()	Write the session out and release the lock

The provider puts two things into every new session: a user holding a Hubzero\User\User, and a registry holding a Hubzero\Config\Registry. The registry is what User::getState() and User::setState() read and write, and what Request::getState() uses to remember a list screen's filters between requests. Use those rather than writing filter state into the session yourself.