TYPO3 12.4 API: UserSessionManager

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);

Interfaces

LoggerAwareInterface

Constants

GARBAGE_COLLECTION_LIFETIME = 86400
LIFETIME_OF_ANONYMOUS_SESSION_DATA = 86400
SESSION_ID_LENGTH = 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

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

$garbageCollectionForAnonymousSessions


    protected
        int
    $garbageCollectionForAnonymousSessions
     = self::LIFETIME_OF_ANONYMOUS_SESSION_DATA

$ipLocker


    protected
        IpLocker
    $ipLocker

$loginType


    protected
        string
    $loginType

$sessionBackend


    protected
        SessionBackendInterface
    $sessionBackend

$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.

__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

Internal

it is recommended to use the factory method "create"

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

Internal

this is only used as a bridge for existing methods, might be removed or renamed without further notice

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

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

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<string|int, mixed> $existingSessionRecord = [] ][, bool $anonymous = false ]) : UserSession

Parameters

$sessionId : string: The session id
$existingSessionRecord : array<string|int, mixed> = []: If given, this session record will be used instead of fetching again
$anonymous : bool = false: If true session will be regenerated as anonymous session

Return values

UserSession

removeSession()

Removes a given session from the session backend


    public
                    removeSession(UserSession $session) : void

Parameters

$session : UserSession

updateSession()

Updates the session data + timestamp in the session backend


    public
                    updateSession(UserSession $session) : UserSession

Parameters

$session : UserSession

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

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<string|int, mixed>|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<string|int, mixed>|null = null

Return values

UserSession

setGarbageCollectionTimeoutForAnonymousSessions()


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

Parameters

$garbageCollectionForAnonymousSessions : int = 0

UserSessionManager implements LoggerAwareInterface uses LoggerAwareTrait, CookieScopeTrait

Table of Contents

Interfaces

Constants

Properties

Methods

Constants

GARBAGE_COLLECTION_LIFETIME

LIFETIME_OF_ANONYMOUS_SESSION_DATA

SESSION_ID_LENGTH

Properties

$garbageCollectionForAnonymousSessions

$ipLocker

$loginType

$sessionBackend

$sessionLifetime

Methods

__construct()

Parameters

collectGarbage()

Parameters

create()

Parameters

Return values

createAnonymousSession()

Return values

createFromGlobalCookieOrAnonymous()

Parameters

Return values

createFromRequestOrAnonymous()

Parameters

Return values

createSessionFromStorage()

Parameters

Return values

elevateToFixatedUserSession()

Parameters

Tags

Return values

fixateAnonymousSession()

Parameters

Tags

Return values

hasExpired()

Parameters

Return values

isSessionPersisted()

Parameters

Return values

regenerateSession()

Parameters

Tags

Return values

removeSession()

Parameters

updateSession()

Parameters

Return values

updateSessionTimestamp()

Parameters

Tags

Return values

willExpire()

Parameters

Return values

createSessionId()

Return values

getSessionFromSessionId()

Parameters

Return values

recreateUserSession()

Parameters

Tags

Return values

setGarbageCollectionTimeoutForAnonymousSessions()

Parameters