Feature: #93023 - Introduce UserSession and UserSessionManager 

See forge#93023

Description 

As described in Deprecation: #93023 - Reworked session handling the whole session handling in the TYPO3 Core was restructured by moving it out of the user authentication objects into dedicated classes, namely UserSession and UserSessionManager.

The UserSession object contains of all necessary information regarding a users session, for website visitors with session data (e.g. shopping 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 permanent and so on. This replaces the so called sessionRecord which was an array used in the user authentication objects.

This means, there is now a proper object which can be used to change and retrieve information in an object-oriented way. It also features a toArray() function to obtain these information in the "old" format.

Using the static factory methods createFromRecord() and createNonFixated() one can easily create a new session object.

Public Methods within UserSession 

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.

It should however be always considered to use the UserSessionManager for creating new sessions since this manager acts as the main factory for user sessions and handles all necessary tasks like fetching, evaluating and persisting them. Effectively encapsulating all calls to the SessionManager which is used for the Session Backend.

The UserSessionManager can be retrieved using it's static factory method create().

As already mentioned you can then use the UserSessionManager to work with user sessions. A couple of public methods are available.

Public Methods within UserSessionManager 

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.

Impact 

The user authentication classes such as BackendUserAuthentication, FrontendUserAuthentication and their abstract parent class AbstractUserAuthentication, do now not longer directly manage the corresponding user session. Therefore these objects do not longer include the session data and do not know about the specific session backend implementation.

The main benefit is the centralized handling of sessions via the new UserSession object which contains of all relevant information and the UserSessionManager. Latter should be used as factory to create new sessions for various use-cases.