The MODX Settings Hierarchy

A look at the various settings in MODX, their hierarchy, and how MODX processes them.

By Bob Ray  |  January 6, 2026  |  3 min read
Community MODX CMS Tutorials
The MODX Settings Hierarchy

In my previous article, we looked at MODX settings in general. We raised the question: since there are four kinds of settings, all accessed with the same type of MODX tag, which setting's value will you get if more than one setting has the same name. We'll look at that question in this article.

The Settings Hierarchy

Suppose that you have the following four settings, one of each type. All with the same key, but different values:

Key:my_setting

Values:

  • System Setting — "This is a System Setting"
  • Context Setting — "This is a Context Setting"
  • User Group Setting — "This is a User Group Setting"
  • User Setting — "This is a User Setting"

Let's say the Context Setting is for the 'web' context, which you're in. The User Group Setting is for the Editor's Group, which you're a member of, and the User Setting is your user setting. What will this tag display?

[[++my_setting]]

If you guessed "This is a User Setting," pat yourself on the back. You might think from the name and scope that System Settings would have the highest priority. In fact, they have the lowest. Any other applicable setting with the same name will override a System Setting. The more specific the setting, the higher its priority. Context settings override System Settings. User Group Settings override Context Settings. User Settings override User Group Settings.

Under the Hood

In case you're curious, let's look at how MODX handles the settings internally. You might think that MODX searches through the various settings in turn whenever it sees a setting tag, but it's actually a much more efficient process. MODX creates a single array that can be accessed from anywhere in MODX (it's $modx->config, part of the $modx object). First, MODX creates the config array from all the System Settings. Then, it gets all Context Settings from the current context, merging them into the config array, overwriting any System Settings with the same name. Then, it gets all the user groups the current user belongs to and merges them into the config array in an order determined by the groups' ranks, and the user's authority level. The user's primary group goes in last, so anything there will override the settings in other groups. Finally, the user settings for the current user are merged into the config array, overwriting any setting with the same name.

When MODX sees a setting tag, all it has to do is use the key to get the associated value in the $modx->config array and replace the tag with it.

It sounds like a laborious process, but the PHP array_merge() method is quite fast, and usually, the number of non-System-Setting entries that apply is quite small. The System Settings and Context Settings are cached, which also speeds up the process.

You can see a snapshot of the config array with code like this:

echo print_r($modx->config, true);

// or in a snippet:

return print_r($modx->config, true);

The code above will produce a long list of keys and values. Many MODX extras create their own SystemSettings and there are other things MODX saves in there. On my local machine, it's more than 600 lines.

Important: Be careful where you put that code! Never put anywhere a random visitor to your website could see it. When I last looked at it locally, it contained my database username and password, my Gmail username and password (in the form of SMTP settings), my email address, and some other sensitive data.

Coming Up

In this article, we've seen how to use MODX settings in tags. In the next one, we'll look at how to create custom settings yourself.

Bob Ray is the author of the MODX: The Official Guide and dozens of MODX Extras including QuickEmail, NewsPublisher, SiteCheck, GoRevo, Personalize, EZfaq, MyComponent and many more. His website is Bob’s Guides. It not only includes a plethora of MODX tutorials but there are some really great bread recipes there, as well.