MODX Settings Hierarchy

Understanding the order of precedence of different types of settings

In the last 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 one's value will you get if more than one setting has the same name. We'll look at that question in this article.

MODX logo

The Settings Hierarchy

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

Key: my_setting


  • 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 the current MODX user is a member of, and the User Setting is for the current MODX user. What will this tag display?


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 there with the same names.

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.

Coming Up

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

Looking for high-quality, MODX-friendly hosting? As of May 2016, Bob's Guides is hosted at A2 hosting. (More information in the box below.)

Comments (0)

Please login to comment.