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 |
getUserId() |
Int or NULL |
Returns the user id the session belongs to. Can also return |
getLastUpdated() |
Int |
Returns the timestamp of the last session data update. This is the
|
set($key, $value) |
Void |
Set or update session data value for a given key. It's also internally used
if calling |
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
|
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 |
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 |
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
|
createFromGlobalCookieOrAnonymous($cookieName) |
Creates and returns a session from a global cookie ( |
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 |
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.