Extending the user settings

Deprecated since version 14.2

The method \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addFieldsToUserSettings() has been deprecated in favor of the new addUserSetting() method.

Adding fields to User Settings is done in a TCA Overrides file.

Here is an example taken from the "examples" extension:

EXT:examples/Configuration/TCA/Overrides/be_users.php

<?php

declare(strict_types=1);

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

ExtensionManagementUtility::addUserSetting(
    'mobile',
    [
        'label' => 'LLL:examples.db:be_users.tx_examples_mobile',
        'config' => [
            'type' => 'input',
        ],
    ],
    'after:email',
);

The third parameter in the call to addUserSetting() is used to position the new field. In this example we add it after the existing "email" field.

The new field is then displayed in the user settings after clearing the caches.

TCA available for the user settings module

The user_settings TCA column has the following structure:

columns

Array of field configurations, each containing:

label: The field label (LLL reference or string)
config: Standard TCA config array (type, renderType, items, etc.)
table (optional): Set to 'be_users' if the field is stored in a be_users table column

showitem

Comma-separated list of fields to display, supports --div--; for tabs

Available field types:

input - Text input field
number - Number input field
email - Email input field
password - Password input field
check with :renderType => 'checkboxToggle' - Checkbox/toggle
select with renderType => 'selectSingle' - Select dropdown
language - Language selector

"On Click" / "On Confirmation" JavaScript Callbacks

PSR-14 event AddUserSettingsJavaScriptModulesEvent can be used to inject a JavaScript module to handle custom JavaScript events.

Migration from addFieldsToUserSettings to addUserSetting

Replace the two-step approach with the new addUserSetting() method. Note that the new method uses TCA-style configuration and should be called from Configuration/TCA/Overrides/be_users.php instead of ext_tables.php.

Before:

ext_tables.php (before)

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

$GLOBALS['TYPO3_USER_SETTINGS']['columns']['myCustomSetting'] = [
    'type' => 'check',
    'label' => 'my_extension.messages:myCustomSetting',
];
ExtensionManagementUtility::addFieldsToUserSettings(
    'myCustomSetting',
    'after:emailMeAtLogin'
);

After:

Configuration/TCA/Overrides/be_users.php (after)

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

ExtensionManagementUtility::addUserSetting(
    'myCustomSetting',
    [
        'label' => 'my_extension.messages:myCustomSetting',
        'config' => [
            'type' => 'check',
            'renderType' => 'checkboxToggle',
        ],
    ],
    'after:emailMeAtLogin'
);