From 2fec88145db1862508d370ba9d580d7126dcc712 Mon Sep 17 00:00:00 2001 From: Christoph Wurst Date: Thu, 26 Jan 2023 10:16:56 +0100 Subject: [PATCH] feat(dev-manual): Document UseSession attribute Signed-off-by: Christoph Wurst --- .../app_upgrade_guide/upgrade_to_26.rst | 7 ++++ developer_manual/basics/controllers.rst | 42 +++++++++++++++---- 2 files changed, 42 insertions(+), 7 deletions(-) diff --git a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_26.rst b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_26.rst index 37614d53159..8bc40c6f800 100644 --- a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_26.rst +++ b/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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/developer_manual/basics/controllers.rst b/developer_manual/basics/controllers.rst index dd8807906d4..08ace80d5d6 100644 --- a/developer_manual/basics/controllers.rst +++ b/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 `_ 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 `_. +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 `_. 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'];