System Settings

Last updated Oct 20th, 2026 | Page history | Improve this page | Report an issue

Support the team building MODX with a monthly donation.

The budget raised through OpenCollective is transparent, including payouts, and any contributor can apply to be paid for their work on MODX.

Backers

Budget

$186 per month—let's make that $500!

Learn more

System settings are site-wide configuration values. Edit them in System → System Settings. In templates, read a setting as [[++key]]; in PHP, use $modx->getOption('key').

Overriding Settings (Inheritance)¶

A setting can be overridden at four levels. For a signed-in user, MODX checks them in this order:

User setting
User group setting
Context setting (in the manager, usually mgr)
System setting

Creating a System Setting in the Manager¶

Open System → System Settings and click Create.

Parameters¶

Field	Purpose
Key	Unique name used in `[[++key]]` and `getOption()`.
Name	Label in the settings grid; can be localized.
Field Type	xtype used to render the field; see Types of System Settings.
Namespace	Folder inside `core/components/`, as with Custom Manager Pages.
Area Lexicon Entry	Groups settings that share the same value.
Value	Default value.
Description	Help text; can be localized.

Localization¶

The Name and Description come from lexicon entries:

Name: setting_ + key
Description: setting_ + key + _desc

For a package, these entries live in core/components/<namespace>/lexicon/<language>/default.inc.php:

$_lang['setting_quip.emailsFrom'] = 'From Email';
$_lang['setting_quip.emailsFrom_desc'] = 'The email address to send system emails from.';

Reading a Setting in Code¶

Pass the setting key to getOption():

$siteStartId = $modx->getOption('site_start');

getOption() reads the settings cache, not the database.

Saving a Setting in Code¶

A value from getOption() is cached and read-only. To change a setting, load its modSystemSetting object, update and save it, then clear the cache.

Update the object¶

use MODX\Revolution\modSystemSetting;

$setting = $modx->getObject(modSystemSetting::class, 'site_name');
if ($setting) {
    $setting->set('value', 'My New Site Name');
    $setting->save();
}

Clear the cache¶

Saving does not refresh the settings cache. Clear system_settings; add resource if the value is used on the front end:

$modx->cacheManager->refresh([
    'system_settings' => [],
    'resource' => [],
]);

Read setting metadata¶

use MODX\Revolution\modSystemSetting;

$setting = $modx->getObject(modSystemSetting::class, 'site_name');
print_r($setting->toArray());

Group settings by area or by key prefix.

By area¶

use MODX\Revolution\modSystemSetting;

$relatedSettings = $modx->getCollection(modSystemSetting::class, ['area' => 'mail']);
foreach ($relatedSettings as $setting) {
    print $setting->get('value');
}

By key prefix¶

use MODX\Revolution\modSystemSetting;

$query = $modx->newQuery(modSystemSetting::class);
$query->where(['key:LIKE' => 'quip.%']);
$relatedSettings = $modx->getCollection(modSystemSetting::class, $query);
foreach ($relatedSettings as $setting) {
    print $setting->get('value');
}

Creating a Setting in Code¶

use MODX\Revolution\modSystemSetting;

$setting = $modx->newObject(modSystemSetting::class);
$setting->set('key', 'mykey');
$setting->set('value', 'my_value');
$setting->set('xtype', 'textfield');
$setting->set('namespace', 'my_namespace');
$setting->set('area', 'MyArea');
$setting->save();

$modx->cacheManager->refresh(['system_settings' => []]);

Add matching lexicon entries so the setting gets a label and description:

$_lang['setting_mykey'] = 'Name of My Setting';
$_lang['setting_mykey_desc'] = 'Description of my key';

To print a setting label in a template or a Custom Manager Page, call the lexicon tag with the setting topic:

[[!%setting_emailsender? &topic=`setting` &namespace=`core` &language=`en`]]

Types of System Settings¶

The xtype attribute sets the field used in the manager:

xtype	Field
`combo-boolean`	Yes/No; stores `1` or `0`
`textfield`	Single-line text
`textarea`	Multi-line text
`text-password`	Masked text
`numberfield`	Number
`modx-combo-language`	Language picker
`modx-combo-source`	Media Source picker
`modx-combo-template`	Template picker
`modx-combo-content-type`	Content type picker
`modx-combo-charset`	Character set picker
`modx-combo-rte`	Rich-text editor picker
`modx-combo-context`	Context picker
`modx-combo-namespace`	Namespace picker
`modx-combo-manager-theme`	Manager theme picker

Settings List¶