TYPO3 v15 dev-main snapshot ()

2026-08-10 22:31:09 +02:00
commit af8cc155b5
6818 changed files with 642608 additions and 0 deletions
@@ -0,0 +1,125 @@
+.. include:: /Includes.rst.txt
+
+.. _feature-96895:
+
+==============================================
+Feature: #96895 - Introduce Module data object
+==============================================
+
+See :issue:`96895`
+
+Description
+===========
+
+To further improve the handling of TYPO3 backend modules, the module
+registration API, introduced in :issue:`96733`, is extended by the new
+:php:`TYPO3\CMS\Backend\Module\ModuleData` object.
+
+The :php:`ModuleData` object contains the user specific module settings,
+e.g. whether the clipboard is shown, for the requested module. Those settings
+are fetched from the users' session. A PSR-15 middleware does automatically
+create the object from the stored user data and attach it to the PSR-7 Request.
+
+Through the module registration one can define, which properties can
+be overwritten via :php:`GET` / :php:`POST` and their default value.
+
+The whole determination is done before the requested route target - usually
+a backend controller - is called. This means, the route target can just
+read the final module data and does no longer have to fiddle around with
+overwriting and persisting the data manually.
+
+Previously, reading, overwriting and persisting of module data (settings)
+was done in the controller:
+
+..  code-block:: php
+
+    // Classes/Controller/MyController.php
+
+    $MOD_MENU = [
+        'allowedProperty' => '',
+        'anotherAllowedProperty' => true
+    ];
+
+    $MOD_SETTINGS = BackendUtility::getModuleData(
+        $MOD_MENU,
+        $request->getParsedBody()['SET'] ?? $request->getQueryParams()['SET'] ?? [],
+        'my_module'
+    );
+
+This is now automatically done by a new PSR-15 middleware. The "allowed"
+properties are defined with their default value in the module registration:
+
+..  code-block:: php
+
+    // Configuration/Backend/Modules.php
+
+    'moduleData' => [
+        'allowedProperty' => '',
+        'anotherAllowedProperty' => true,
+    ],
+
+    // Classes/Controller/MyController.php
+
+    $MOD_SETTINGS = $request->getAttribute('moduleData');
+
+The :php:`ModuleData` object provides the following methods:
+
+-------------------------+-----------------------+----------------------------------------------------+
+| Method                  | Parameters            | Description                                        |
+=========================+=======================+====================================================+
+| createFromModule()      | :php:`$module`        | Create a new object for the given module, while    |
+|                         | :php:`$data`          | overwriting the default values with :php:`$data`.  |
+-------------------------+-----------------------+----------------------------------------------------+
+| getModuleIdentifier()   |                       | Returns the related module identifier              |
+-------------------------+-----------------------+----------------------------------------------------+
+| get()                   | :php:`$propertyName`  | Returns the value for :php:`$propertyName`, or the |
+|                         | :php:`$default`       | :php:`$default`, if not set.                       |
+-------------------------+-----------------------+----------------------------------------------------+
+| set()                   | :php:`$propertyName`  | Updates :php:`$propertyName` with the given        |
+|                         | :php:`$value`         | :php:`$value`.                                     |
+-------------------------+-----------------------+----------------------------------------------------+
+| has()                   | :php:`$propertyName`  | Whether :php:`$propertyName` exists.               |
+-------------------------+-----------------------+----------------------------------------------------+
+| clean()                 | :php:`$propertyName`  | Cleans a single property by the given allowed      |
+|                         | :php:`$allowedValues` | list and falls back to either the default value    |
+|                         |                       | or the first allowed value.                        |
+-------------------------+-----------------------+----------------------------------------------------+
+| cleanUp()               | :php:`$allowedData`   | Cleans up all module data defined in the given     |
+|                         | :php:`$useKeys`       | list of allowed data. Usually called with          |
+|                         |                       | :php:`$MOD_MENU` in a controller with module menu. |
+-------------------------+-----------------------+----------------------------------------------------+
+| toArray()               |                       | Returns the module data as :php:`array`.           |
+-------------------------+-----------------------+----------------------------------------------------+
+
+In case a controller needs to store changed module data, this can still be done
+using :php:`$backendUser->pushModuleData('my_module', $this->moduleData->toArray());`.
+
+.. note::
+
+    It's still possible to store and retrieve arbitrary module data. The
+    definition of :php:`moduleData` in the module registration only defines,
+    which properties can be overwritten in a request (with :php:`GET` / :php:`POST`).
+
+To restrict the values of module data properties, the given :php:`ModuleData`
+object can be cleaned e.g. in a controller:
+
+..  code-block:: php
+
+    $allowedValues = ['foo', 'bar'];
+
+    $this->moduleData->clean('property', $allowedValues);
+
+If :php:`ModuleData` contains :php:`property`, the value is checked
+against the :php:`$allowedValues` list. If the current value is valid,
+nothing happens. Otherwise the value is either changed to the default
+or if this value is also not allowed, to the first allowed value.
+
+Impact
+======
+
+The new :php:`ModuleData` object is available as new attribute of the
+PSR-7 Request - in case a TYPO3 backend module is requested - and contains
+the stored module data, which might have been overwritten through the current
+request (with :php:`GET` / :php:`POST`).
+
+.. index:: Backend, PHP-API, ext:backend