Breaking-93023-ReworkedSessionHandling.rst 6.47 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
.. include:: ../../Includes.txt

.. _changelog-Breaking-93023-ReworkedSessionHandling:

============================================
Breaking: #93023 - Reworked session handling
============================================

See :issue:`93023`

Description
===========

The overall session handling withing TYPO3 Core has been overhauled. This was
done to separate the actual User object, the Authentication process and the
session handling.

18
The main result of this refactoring is the user authentication objects such as
19
20
21
22
23
24
25
26
27
28
29
30
31
:php:`BackendUserAuthentication` and :php:`FrontendUserAuthentication`
do not longer contain the session data directly. Instead this is now encapsulated
in a :php:`UserSession` object which is handled by the new
:php:`UserSessionManager`.

Furthermore the user authentication objects internally do not longer know about
a specific session backend implementation, since this is also wrapped by the
:php:`UserSessionManager`. This also means it is not possible to create sessions
outside of the new session manager anymore.

For this purpose there are several changes within the user authentication
classes which are described below.

32
The array :php:`AbstractUserAuthentication->user` previously contained the logged-in
33
user record (from be_users / fe_users database table) AND the session record
34
prefixed via :php:`ses_*` array properties. This has been removed, to separate
35
the functionality. Instead, all session properties are placed inside the
36
:php:`UserSession` object, accessible via e.g. :php:`$GLOBALS[BE_USER]->getSession()`.
37
38
39
40

The following public properties within :php:`AbstractUserAuthentication` and
its subclasses have been removed:

41
42
43
44
45
46
*  :php:`TYPO3\CMS\Core\Authentication\AbstractUserAuthentication->id`
*  :php:`TYPO3\CMS\Core\Authentication\AbstractUserAuthentication->hash_length`
*  :php:`TYPO3\CMS\Core\Authentication\AbstractUserAuthentication->sessionTimeout`
*  :php:`TYPO3\CMS\Core\Authentication\AbstractUserAuthentication->gc_time`
*  :php:`TYPO3\CMS\Core\Authentication\AbstractUserAuthentication->gc_probability`
*  :php:`TYPO3\CMS\Core\Authentication\AbstractUserAuthentication->newSessionID`
47
48
49
50

The following public methods within :php:`AbstractUserAuthentication` and its
subclasses have been removed:

51
52
53
*  :php:`TYPO3\CMS\Core\Authentication\AbstractUserAuthentication->getNewSessionRecord()`
*  :php:`TYPO3\CMS\Core\Authentication\AbstractUserAuthentication->getSessionId()`
*  :php:`TYPO3\CMS\Core\Authentication\AbstractUserAuthentication->isExistingSessionRecord()`
54
55
56
57

The following public property within :php:`AbstractUserAuthentication` has
changed their visibility to :php:`protected`:

58
*  :php:`TYPO3\CMS\Core\Authentication\AbstractUserAuthentication->lifetime`
59
60
61
62

The following public methods within :php:`AbstractUserAuthentication` and its
subclasses have changed their return type:

63
64
65
*  :php:`TYPO3\CMS\Frontend\Authentication\FrontendUserAuthentication->createUserSession()`
   now returns :php:`TYPO3\CMS\Core\Session\UserSession` and the first parameter
   :php:`$tempuser` is now type-hinted :php:`array`.
66
67
68
69

The following public properties within :php:`FrontendUserAuthentication` have
been removed:

70
*  :php:`TYPO3\CMS\Frontend\Authentication\FrontendUserAuthentication->sesData_change`
71
72
73

The following database fields have been removed:

74
75
*  :sql:`be_sessions.ses_backuserid`
*  :sql:`fe_sessions.ses_anonymous`
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107


Impact
======

Accessing a dropped property or calling a dropped method will raise a fatal PHP
error.

Accessing a property whose visibility was changed to :php:`protected` will also
raise a fatal PHP error if no deprecation functionality is in place. See
:ref:`changelog-Deprecation-93023-ReworkedSessionHandling` for more information.

Calling a method whose parameter signature changed with a wrong type will raise
a PHP type error.

Directly querying a dropped database field will raise a doctrine dbal exception.


Affected Installations
======================

All TYPO3 installations with custom extensions directly accessing or calling
the changed properties or methods.


Migration
=========

The :php:`sessionTimeout` property is now set internally to the value of the
global configuration :php:`(int)$GLOBALS['TYPO3_CONF_VARS'][$loginType]['sessionTimeout'];`.
This value can also be set dynamically in e.g. a middleware if needed. Because
it is only needed for User Session objects, it is now resolved within
108
the :php:`UserSessionManager` object.
109
110
111
112
113
114
115
116
117
118
119
120

:php:`gc_time` is still set to `86400` per default and will be overwritten
with the value from :php:`sessionTimeout` (see above) if greater than `0`.

Since it's very unlikely that :php:`gc_probability` will be changed in
custom code there is no direct way to set a custom value anymore. It's now
directly set to `1` in the consuming method
:php:`UserSessionManager->collectGarbage()`. If your custom code however rely
on another value you can call :php:`UserSessionManager->collectGarbage()`
in your code by providing a custom value as first argument for
:php:`$garbageCollectionProbability`.

121
The property :php:`newSessionID` is now available in :php:`UserSession->isNew()`.
122
123

Use the :php:`UserSessionManager->elevateToFixatedUserSession()` as a
124
replacement for :php:`getNewSessionRecord()` to migrate an anonymous session
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
to a user-bound session.

If you directly call :php:`createUserSession()` in your custom code make sure
to pass an :php:`array` as argument for :php:`$tempuser` and to handle the
returned :php:`UserSession` object accordingly.

Use :php:`UserSession->dataWasUpdated()` as replacement for
:php:`FrontendUserAuthentication->sesData_change`.

The :sql:`be_sessions.ses_backuserid` field was migrated into the session data
and is now available inside :php:`UserSession->data`, which can be accessed
using :php:`get()` or :php:`getAll()`. Since this value is only present in
"switch-user" sessions, it's very unlikely that custom code is directly
accessing it. If you however perform database queries using this field,
then they have to be adjusted accordingly.

The :sql:`fe_sessions.ses_anonymous` field is not needed anymore since this
information can also be obtained using the :sql:`fe_sessions.ses_userid` field.
If it's lower or equals `0` the session is an anonymous one. If you perform
144
database queries using this field, change it to use use :sql:`ses_userid` instead.
145
146
147
148
149
150
If a session is anonymous can furthermore be checked using
:php:`UserSession->isAnonymous()`.

Related
=======

151
152
-  :ref:`changelog-Deprecation-93023-ReworkedSessionHandling`
-  :ref:`changelog-Feature-93023-IntroduceUserSessionAndUserSessionManager`
153
154

.. index:: PHP-API, FullyScanned, ext:core