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,108 @@
+..  include:: /Includes.rst.txt
+
+..  _feature-108843-1738600001:
+
+============================================================
+Feature: #108843 - User settings configuration migrated to TCA
+============================================================
+
+See :issue:`108843`
+See :issue:`108832`
+
+Description
+===========
+
+The backend user profile settings configuration that was previously stored in
+:php:`$GLOBALS['TYPO3_USER_SETTINGS']` is now available in TCA at
+:php:`$GLOBALS['TCA']['be_users']['columns']['user_settings']`.
+
+This allows user settings to benefit from TCA-based tooling and provides
+a consistent API that extensions already use for other configuration.
+
+A new method
+:php:`ExtensionManagementUtility::addUserSetting()` has been introduced to
+simplify adding custom fields to user profile settings.
+
+Impact
+======
+
+Extensions can add custom fields to backend user profile settings using
+the new :php:`addUserSetting()` method in
+:file:`Configuration/TCA/Overrides/be_users.php`:
+
+..  code-block:: php
+
+    // Configuration/TCA/Overrides/be_users.php
+    \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addUserSetting(
+        'myCustomSetting',
+        [
+            'label' => 'LLL:EXT:my_ext/Resources/Private/Language/locallang.xlf:myCustomSetting',
+            'config' => [
+                'type' => 'check',
+                'renderType' => 'checkboxToggle',
+            ],
+        ],
+        'after:emailMeAtLogin'
+    );
+
+Alternatively, extensions can directly modify the TCA:
+
+..  code-block:: php
+
+    // Configuration/TCA/Overrides/be_users.php
+    $GLOBALS['TCA']['be_users']['columns']['user_settings']['columns']['myCustomSetting'] = [
+        'label' => 'LLL:my_extension.messages:myCustomSetting',
+        'config' => [
+            'type' => 'check',
+            'renderType' => 'checkboxToggle',
+        ],
+    ];
+
+    // Add to showitem
+    $GLOBALS['TCA']['be_users']['columns']['user_settings']['showitem'] .= ',myCustomSetting';
+
+Structure
+---------
+
+The :php:`user_settings` TCA column has the following structure:
+
+:php:`columns`
+    Array of field configurations, each containing:
+
+    :php:`label`
+        The field label (LLL reference or string)
+
+    :php:`config`
+        Standard TCA config array (type, renderType, items, etc.)
+
+    :php:`table` (optional)
+        Set to :php:`'be_users'` if the field is stored in a
+        :sql:`be_users` table column
+
+:php:`showitem`
+    Comma-separated list of fields to display; supports
+    :php:`--div--;` for tabs
+
+Available field types
+---------------------
+
+*   :php:`input` - Text input field
+*   :php:`number` - Number input field
+*   :php:`email` - Email input field
+*   :php:`password` - Password input field
+*   :php:`check` with :php:`renderType => 'checkboxToggle'` -
+    Checkbox or toggle
+*   :php:`select` with :php:`renderType => 'selectSingle'` -
+    Select field
+*   :php:`language` - Language selector
+
+Backward compatibility
+----------------------
+
+For backward compatibility, the legacy
+:php:`$GLOBALS['TYPO3_USER_SETTINGS']` array is still supported. Third-party
+additions are automatically migrated to TCA after all
+:file:`ext_tables.php` files have been loaded. However, this approach is
+deprecated, and extensions should migrate to the new TCA-based API.
+
+..  index:: Backend, TCA, PHP-API, ext:setup