User session management

User sessions in TYPO3 are represented as UserSession objects. The TYPO3 authentication service chain creates or updates user sessions when authenticating users.

The UserSession object contains all information regarding a users' session, for website visitors with session data (e.g. basket for anonymous / not-logged-in users), for frontend users as well as authenticated backend users. These are for example, the session id, the session data, if a session was updated, if the session is anonymous, or if it is marked as permanent and so on.

The UserSession object can be used to change and retrieve information in an object-oriented way.

For creating UserSession-objects the UserSessionManager must be used since this manager acts as the main factory for user sessions and therefore handles all necessary tasks like fetching, evaluating and persisting them. Effectively encapsulating all calls to the SessionManager which is used for the session backend.

Public API of UserSessionManager

The UserSessionManager can be retrieved using its static factory method create():

EXT:some_extension/Classes/Controller/SomeController.php 
use TYPO3\CMS\Core\Session\UserSessionManager;

$loginType = 'BE'; // or 'FE' for frontend
$userSessionManager = UserSessionManager::create($loginType);
Copied!

You can then use the UserSessionManager to work with user sessions. A couple of public methods are available:

Method Description
createFromRequestOrAnonymous($request, $cookieName) Creates and returns a session from the given request. If the given cookieName can not be obtained from the request an anonymous session will be returned.
createFromGlobalCookieOrAnonymous($cookieName) Creates and returns a session from a global cookie ($_COOKIE). If no cookie can be found for the given name, an anonymous session will be returned. It is recommended to use the PSR-7-Request based method instead, as this method is scheduled for removal in TYPO3 v13.0.
createAnonymousSession() Creates and returns an anonymous session object (not persisted).
createSessionFromStorage($sessionId) Creates and returns a new session object for a given session id.
hasExpired($session) Checks whether a given user session object has expired.
willExpire($session, $gracePeriod) Checks whether a given user session will expire within the given grace period.
fixateAnonymousSession($session, $isPermanent) Persists an anonymous session without a user logged in, in order to store session data between requests.
elevateToFixatedUserSession($session, $userId, $isPermanent) Removes existing entries, creates and returns a new user session object. See regenerateSession() below.
regenerateSession($sessionId, $sessionRecord, $anonymous) Regenerates the given session. This method should be used whenever a user proceeds to a higher authorization level, e.g. when an anonymous session is now authenticated.
updateSessionTimestamp($session) Updates the session timestamp for the given user session if the session is marked as "needs update" (which means the current timestamp is greater than "last updated + a specified gracetime").
isSessionPersisted($session) Checks whether a given session is already persisted.
removeSession($session) Removes a given session from the session backend.
updateSession($session) Updates the session data + timestamp in the session backend.
collectGarbage($garbageCollectionProbability) | Calls the session backends collectGarbage() method.

Public API of UserSession

The session object created or retrieved by the UserSessionManager provides the following API methods:

Method Return type Description
getIdentifier() String Returns the session id. This is the ses_id respectively the AbstractUserAuthentication->id.
getUserId() Int or NULL Returns the user id the session belongs to. Can also return 0 or NULL Which indicates an anonymous session. This is the ses_userid.
getLastUpdated() Int Returns the timestamp of the last session data update. This is the ses_tstamp.
set($key, $value) Void Set or update session data value for a given key. It's also internally used if calling AbstractUserAuthentication->setSessionData().
get($key) Mixed Returns the session data for the given key or NULL if the key does not exist. It's internally used if calling AbstractUserAuthentication->getSessionData().
getData() Array Returns the whole data array.
hasData() Bool Checks whether the session has some data assigned.
overrideData($data) Void Overrides the whole data array. Can also be used to unset the array. This also sets the $wasUpdated pointer to TRUE
dataWasUpdated() Bool Checks whether the session data has been updated.
isAnonymous() Bool Check if the user session is an anonymous one. This means, the session does not belong to a logged-in user.
getIpLock() string Returns the ipLock state of the session
isNew() Bool Checks whether the session is new.
isPermanent() Bool Checks whether the session was marked as permanent on creation.
needsUpdate() Bool Checks whether the session has to be updated.
toArray() Array Returns the session and its data as array in the old sessionRecord format.