Merge pull request #9589 from nextcloud/feat/dev-manual/usesession-at…

…tribute

feat(dev-manual): Document UseSession attribute

developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_26.rst

@@ -33,6 +33,13 @@ tbd
 Back-end changes
 ----------------
 
+Migration from PHPDoc annotations to native PHP attributes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Nextcloud 26 supports PHP8.0 and later. This allows the migration from PHPDoc annotations to native attributes.
+
+* ``@UseSession`` should be replaced with ``#[UseSession]``. ``@UseSession`` will be removed in a future release. See :ref:`controller-use-session`.
+
 Planned removal of PSR-0 class loading
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

developer_manual/basics/controllers.rst

@@ -214,6 +214,7 @@ Headers, files, cookies and environment variables can be accessed directly from
 
 Why should those values be accessed from the request object and not from the global array like $_FILES? Simple: `because it's bad practice <http://c2.com/cgi/wiki?GlobalVariablesAreBad>`_ and will make testing harder.
 
+.. _controller-use-session:
 
 Reading and writing session variables
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -222,15 +223,44 @@ To set, get or modify session variables, the ISession object has to be injected
 
 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 immediately 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.
+Alternatively, you can use the ``#[UseSession]`` attribute to automatically open and close the session for you.
+
+.. code-block:: php
+    :emphasize-lines: 2,13
+
+    use OCP\AppFramework\Controller;
+    use OCP\AppFramework\Http\Attribute\UseSession;
+    use OCP\AppFramework\Http\Response;
+
+    class PageController extends Controller {
+
+        #[UseSession]
+        public function writeASessionVariable(): Response {
+            // ...
+        }
+
+    }
+
+.. note:: The ``#[UseSession]`` was added in Nextcloud 26 and requires PHP8.0 or later. If your app targets older releases and PHP7.x then use the deprecated ``@UseSession`` annotation.
+
+    .. code-block:: php
+        :emphasize-lines: 2
+
+        /**
+         * @UseSession
+         */
+        public function writeASessionVariable(): Response {
+            // ....
+        }
+
 
 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 for the whole duration 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/>`_.
+For additional information on how session locking works in PHP see the article 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!
+.. note:: The session is closed automatically for writing, unless you add the ``#[UseSession]`` attribute!
 
 .. code-block:: php
 
@@ -240,6 +270,7 @@ Then session variables can be accessed like this:
     use OCP\ISession;
     use OCP\IRequest;
     use OCP\AppFramework\Controller;
+    use OCP\AppFramework\Http\Attribute\UseSession;
     use OCP\AppFramework\Http\Response;
 
     class PageController extends Controller {
@@ -251,10 +282,7 @@ Then session variables can be accessed like this:
             $this->session = $session;
         }
 
-        /**
-         * The following annotation is only needed for writing session values
-         * @UseSession
-         */
+        #[UseSession]
         public function writeASessionVariable(): Response {
             // read a session variable
             $value = $this->session['value'];