Adapt session handling description to changes in Nextcloud 25

Signed-off-by: Julius Härtl <jus@bitgrid.net>

developer_manual/basics/controllers.rst

@@ -220,6 +220,14 @@ Reading and writing session variables
 
 To set, get or modify session variables, the ISession object has to be injected into the controller.
 
+Nextcloud will read existing session data at the beginning of the request lifecycle and close the session afterwards. This means that in order to write to the session, the session has to be opened first. This is done implicitly when calling the set method, but would close immidiately afterwards. To prevent this, the session has to be explicitly opened by calling the reopen method.
+
+Alternatively you can use the UseSession annotation to automatically open and close the session for you.
+
+In case the session may be read and written by concurrent requests of your application keeping the session open during your controller method execution may be required to ensure that the session is locked and no other request can write to the session at the same time. When reopening the session, the session data will also get updated with the latest changes from other requests. Using the annotation will keep the session lock during the whole time of the controller method execution.
+
+For additional information on how session locking works in PHP see the artile about `PHP Session Locking: How To Prevent Sessions Blocking in PHP requests <https://ma.ttias.be/php-session-locking-prevent-sessions-blocking-in-requests/>`_.
+
 Then session variables can be accessed like this:
 
 .. note:: The session is closed automatically for writing, unless you add the @UseSession annotation!