The definitive guide to eZ Publish settings priority

Every developer who has come in contact with eZ for even a short moment knows what you are talking about if you mention "settings hell": a vast number of configuration settings files that can be spread over many, many directories.

Who has not spent at least a couple of hours pulling hairs trying to understand why something was not working, only to find out that a contradicting setting was set in a file of higher priority?

Despair not, because we're here to help, with the definitive guide to settings priorities!

The goal of the following test is to establish once and for all the priorities of eZ Publish settings, depending on the folders they're set in.

Recap:

Settings can be set in ini files in the following folders:

• settings (default value, applies globally)
• settings/override (applies globally)
• settings/siteaccess/<xxx> (applies only to given sitaccess)

Extensions can also add or modify some settings. Depending on whether the extensions are activated via the ActiveExtensions or ActiveAccessExtensions parameter in file site.ini, the weight and scope of their settings does change:

• extension/<ext>/settings (applies globally)
• extension/<ext>/settings/siteaccess/<xxx> (applies only to given sitaccess)
• extension/<ext>/settings (applies only in siteaccess - when ext. is loaded via ActiveAccessExtensions)
• extension/<ext>/settings/siteaccess/<xxx> (applies only to given sitaccess - when ext. is loaded via ActiveAccessExtensions)

The general setting priority is well known (override > extension > siteaccess > defaults), but what about all those pesky corner cases?

Test setup:

Extensions ext1 and ext2 are loaded in that order in override/site.ini using ActiveExtensions (no dependencies are declared for automatic extension ordering).

Extensions ext1ae and ext2ae are loaded in that order in siteaccess/<xxx>/site.ini using ActiveAccessExtensions (no dependencies are declared).

All 4 extensions declare settings in both extension/<ext>/my.ini and extension/<ext>/siteaccess/<xxx>/my.ini

The test has been executed on a stock eZP 4.5 install. ymmv with other versions.

Test 1: string setting - order of importance

At every possible location a value is set for a custm setting in a file my.ini. The value is then read and displayed in a node template using the operator ezini. When the file source of the current value is identified, the parameter is removed from that location, caches cleared and the template executed again to find the next ocation.

Order of importance of the files (strongest to weakest)
1 'override'
2 'ext1'
3 'ext2'
4 'siteaccess/<xxx>'
5 'ext1/siteaccess/<xxx>'
6 'ext2/siteaccess/<xxx>'
7 'ext1ae/siteaccess/<xxx>'
8 'ext2ae/siteaccess/<xxx>'
9 'ext1ae'
10'ext2ae'
We can notice here that for ActiveAccessExtensions extensions, putting the settings in a siteaccess directory actually makes the settings stronger instead of weaker (the opposite of what happens with extensions loaded globally). Not that locations 7 and 8 make any sense imho, as you are telling eZ two times that you want those settings only to apply to a siteaccess...

Test 2: array setting - loading order

Sometimes you only want to add values to an array setting, and the position of elements within the array is important. Can we assume that the order in which elements are added to the array is the reverse as the order of importance used when a single-valued setting is changed? Let's find out.

At every possible location a value is added to a sigle setting, of type array.

Resulting array:

0 'ext2ae'
1 'ext1ae'
2 'ext1/siteaccess/<xxx>'
3 'ext2/siteaccess/<xxx>'
4 'ext2ae/siteaccess/<xxx>'
5 'ext1ae/siteaccess/<xxx>'
6 'ext2/siteaccess/<xxx>'
7 'ext1/siteaccess/<xxx>'
8 'siteaccess'
9 'ext2'
10 'ext1'
11 'override'

We can notice here a bug: the values declared in ext1/siteaccess/<xxx> and ext2/siteaccess/<xxx> are loaded twice, once before the corresponding values from ActiveAccessExtensions extensions and once afterwards. Apart from that, the order is the inverse of the priorities found above.