UserSessionManager

class \TYPO3\CMS\Core\Session\UserSessionManager

Implements
LoggerAwareInterface
Uses
LoggerAwareTrait, CookieScopeTrait

The purpose of the UserSessionManager is to create new user session objects (acting as a factory), depending on the need / request, and to fetch sessions from the session backend, effectively encapsulating all calls to the `SessionManager`.

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

use TYPO3\CMS\Core\Session\UserSessionManager;

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

Table of Contents

Interfaces

LoggerAwareInterface

Constants

GARBAGE_COLLECTION_LIFETIME  : mixed = 86400
LIFETIME_OF_ANONYMOUS_SESSION_DATA  : mixed = 86400
SESSION_ID_LENGTH  : mixed = 32

Properties

$garbageCollectionForAnonymousSessions  : int
$ipLocker  : IpLocker
$loginType  : string
$sessionBackend  : SessionBackendInterface
$sessionLifetime  : int
Session timeout (on the storage-side, used to know until a session (timestamp) is valid

Methods

__construct()  : mixed
Constructor. Marked as internal, as it is recommended to use the factory method "create"
collectGarbage()  : void
Calls the session backends `collectGarbage()` method
create()  : static
Creates a `UserSessionManager` instance for the given login type. Has several optional arguments used for testing purposes to inject dummy objects if needed.
createAnonymousSession()  : UserSession
Creates and returns an anonymous session object (which is not persisted)
createFromGlobalCookieOrAnonymous()  : UserSession
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.
createFromRequestOrAnonymous()  : UserSession
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.
createSessionFromStorage()  : UserSession
Creates and returns a new session object for a given session id
elevateToFixatedUserSession()  : UserSession
Removes existing entries, creates and returns a new user session object.
fixateAnonymousSession()  : UserSession
Persists an anonymous session without a user logged-in, in order to store session data between requests
hasExpired()  : bool
Checks whether a session has expired. This is also the case if `sessionLifetime` is `0`
isSessionPersisted()  : bool
Checks whether a given session is already persisted
regenerateSession()  : UserSession
Regenerates the given session. This method should be used whenever a user proceeds to a higher authorization level, for example when an anonymous session is now authenticated.
removeSession()  : void
Removes a given session from the session backend
updateSession()  : UserSession
Updates the session data + timestamp in the session backend
updateSessionTimestamp()  : UserSession
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 grace-time").
willExpire()  : bool
Checks whether a given user session will expire within the given grace period
createSessionId()  : string
Creates a new session ID using a random with SESSION_ID_LENGTH as length
getSessionFromSessionId()  : UserSession|null
Tries to fetch a user session form the session backend.
recreateUserSession()  : UserSession
Recreates a `UserSession` object from the existing session data - keeping `new` state.
setGarbageCollectionTimeoutForAnonymousSessions()  : void

Constants

GARBAGE_COLLECTION_LIFETIME

protected mixed GARBAGE_COLLECTION_LIFETIME = 86400

LIFETIME_OF_ANONYMOUS_SESSION_DATA

protected mixed LIFETIME_OF_ANONYMOUS_SESSION_DATA = 86400

SESSION_ID_LENGTH

protected mixed SESSION_ID_LENGTH = 32

Properties

$garbageCollectionForAnonymousSessions

protected int $garbageCollectionForAnonymousSessions = self::LIFETIME_OF_ANONYMOUS_SESSION_DATA

$sessionLifetime

Session timeout (on the storage-side, used to know until a session (timestamp) is valid

protected int $sessionLifetime

If >0: session-timeout in seconds. If =0: Instant logout after login.

Methods

__construct()

Constructor. Marked as internal, as it is recommended to use the factory method "create"

public __construct(SessionBackendInterface $sessionBackend, int $sessionLifetime, IpLocker $ipLocker, string $loginType) : mixed

Parameters

$sessionBackend : SessionBackendInterface
$sessionLifetime : int
$ipLocker : IpLocker
$loginType : string

collectGarbage()

Calls the session backends `collectGarbage()` method

public collectGarbage([int $garbageCollectionProbability = 1 ]) : void

Parameters

$garbageCollectionProbability : int = 1

create()

Creates a `UserSessionManager` instance for the given login type. Has several optional arguments used for testing purposes to inject dummy objects if needed.

public static create(string $loginType[, int|null $sessionLifetime = null ][, SessionManager|null $sessionManager = null ][, IpLocker|null $ipLocker = null ]) : static

Ideally, this factory encapsulates all TYPO3_CONF_VARS options, so the actual object does not need to consider any global state.

Parameters

$loginType : string
$sessionLifetime : int|null = null
$sessionManager : SessionManager|null = null
$ipLocker : IpLocker|null = null

Return values

static

createAnonymousSession()

Creates and returns an anonymous session object (which is not persisted)

public createAnonymousSession() : UserSession

Return values

UserSession

createFromGlobalCookieOrAnonymous()

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.

public createFromGlobalCookieOrAnonymous(string $cookieName) : UserSession

Deprecated

use createFromRequestOrAnonymous() instead. Will be removed in TYPO3 v13.0.

Parameters

$cookieName : string

Return values

UserSession

createFromRequestOrAnonymous()

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.

public createFromRequestOrAnonymous(ServerRequestInterface $request, string $cookieName) : UserSession

Parameters

$request : ServerRequestInterface
$cookieName : string

Name of the cookie that might contain the session

Return values

UserSession —

An existing session if one is stored in the cookie, an anonymous session otherwise

createSessionFromStorage()

Creates and returns a new session object for a given session id

public createSessionFromStorage(string $sessionId) : UserSession

Parameters

$sessionId : string

The session id to be looked up in the session backend

Return values

UserSession —

The created user session object

elevateToFixatedUserSession()

Removes existing entries, creates and returns a new user session object.

public elevateToFixatedUserSession(UserSession $session, int $userId[, bool $isPermanent = false ]) : UserSession

See regenerateSession() below.

Parameters

$session : UserSession

The user session to recreate

$userId : int

The user id the session belongs to

$isPermanent : bool = false

If true, the session will get the ses_permanent flag

Tags

throws
SessionNotCreatedException

Return values

UserSession —

The newly created user session object

fixateAnonymousSession()

Persists an anonymous session without a user logged-in, in order to store session data between requests

public fixateAnonymousSession(UserSession $session[, bool $isPermanent = false ]) : UserSession

Parameters

$session : UserSession

The user session to fixate

$isPermanent : bool = false

If true, the session will get the ses_permanent flag

Tags

throws
SessionNotCreatedException

Return values

UserSession —

a new session object with an updated ses_tstamp (allowing to keep the session alive)

hasExpired()

Checks whether a session has expired. This is also the case if `sessionLifetime` is `0`

public hasExpired(UserSession $session) : bool

Parameters

$session : UserSession

Return values

bool

isSessionPersisted()

Checks whether a given session is already persisted

public isSessionPersisted(UserSession $session) : bool

Parameters

$session : UserSession

Return values

bool

regenerateSession()

Regenerates the given session. This method should be used whenever a user proceeds to a higher authorization level, for example when an anonymous session is now authenticated.

public regenerateSession(string $sessionId[, array $existingSessionRecord = [] ][, bool $anonymous = false ]) : UserSession

Parameters

$sessionId : string

The session id

$existingSessionRecord : array = []

If given, this session record will be used instead of fetching again

$anonymous : bool = false

If true session will be regenerated as anonymous session

Tags

throws
SessionNotCreatedException
throws
SessionNotFoundException

Return values

UserSession

updateSessionTimestamp()

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 grace-time").

public updateSessionTimestamp(UserSession $session) : UserSession

Parameters

$session : UserSession

Tags

throws
SessionNotUpdatedException

Return values

UserSession —

a modified user session with a last updated value if needed

willExpire()

Checks whether a given user session will expire within the given grace period

public willExpire(UserSession $session, int $gracePeriod) : bool

Parameters

$session : UserSession
$gracePeriod : int

in seconds

Return values

bool

createSessionId()

Creates a new session ID using a random with SESSION_ID_LENGTH as length

protected createSessionId() : string

Return values

string

getSessionFromSessionId()

Tries to fetch a user session form the session backend.

protected getSessionFromSessionId(string $id) : UserSession|null

If none is given, an anonymous session will be created.

Parameters

$id : string

Return values

UserSession|null —

The created user session object or null

recreateUserSession()

Recreates a `UserSession` object from the existing session data - keeping `new` state.

protected recreateUserSession(UserSession $session[, array|null $sessionRecord = null ]) : UserSession

This method shall be used to reflect updated low-level session data in corresponding UserSession object.

Parameters

$session : UserSession
$sessionRecord : array|null = null

Tags

throws
SessionNotFoundException

Return values

UserSession

setGarbageCollectionTimeoutForAnonymousSessions()

protected setGarbageCollectionTimeoutForAnonymousSessions([int $garbageCollectionForAnonymousSessions = 0 ]) : void

Parameters

$garbageCollectionForAnonymousSessions : int = 0
On this page