Skip to the content
Documentation
Help Start
Reading in:
  • German: 9,090 of 9,090 pages
About the help in other languages
All help pages

Settings scopes and the order they win in

The places a settings file can live - default, extension, siteaccess, the per-site folders inside extensions, and the global override - the exact order they are read in, and how to choose the right one for a change.

Download as PDF

Address: https://doc.exponential.earth/exphelp/viewer/help/extension-development/part-2-builder/settings-scopes-and-their-order.md

On this page

Settings scopes and the order they win in

Part 2, chapter 2. The previous chapter showed that many files make one value. This chapter names the places those files live, the order the kernel reads them in, and how to pick the right place for a change. The facts come from eZINI::overrideDirs() in lib/ezutils/classes/ezini.php and from the specification INI override directories and placements.

The places

ScopeDirectoryRead forWhat belongs there
defaultsettings/everythingthe kernel's defaults; never edited
siteaccess extensions (sa-extension)extension/<ext>/settings/ of the extensions in ActiveAccessExtensions[]the siteaccesses that switch them onextensions active for one siteaccess only
siteaccess, inside extensions (siteaccess)extension/<ext>/settings/siteaccess/<sa>/, extension/<ext>/settings/override__<group>/, extension/<ext>/settings/override/the siteaccesses an extension ownsper-site settings kept inside an extension
siteaccess (siteaccess)settings/siteaccess/<sa>/one siteaccessthe settings of one site or of the administration
extensionextension/<ext>/settings/every request, for active extensionsthe defaults an extension ships
overridesettings/override/every requestthis installation's own global settings

The order

After the default file, the kernel reads the override directories in this order, and a later file wins:

  1. extension/<ext>/settings/ of the extensions in ActiveAccessExtensions[] (sa-extension),
  2. the extension siteaccess directories, then settings/siteaccess/<sa>/ (both siteaccess),
  3. extension/<ext>/settings/ of the extensions in ActiveExtensions[] (extension),
  4. settings/override/ (override).

So an extension's settings/ lands on one side of settings/siteaccess/<sa>/ or the other depending on how it is switched on: listed in ActiveExtensions[] it is read after the siteaccess and wins over it; listed in a siteaccess's ActiveAccessExtensions[] it is read before the siteaccess and loses to it.

The code is one line:

return array_merge( $dirs['sa-extension'], $dirs['siteaccess'], $dirs['extension'], $dirs['override'] );

Inside one scope, a directory registered later with eZINI::prependOverrideDir() stands earlier in the list and so has lower priority. For extensions this means: an extension earlier in ActiveExtensions[] wins over a later one, which is why an installation's own settings extension is usually listed first. The same holds among the extensions of ActiveAccessExtensions[], inside the sa-extension scope.

Note

Notice that the extension scope is read after the siteaccess scope. A value an extension in ActiveExtensions[] ships in extension/<ext>/settings/ beats the same value in settings/siteaccess/<sa>/. When a site needs a different value than an extension's default, put it in settings/override/ (which applies to every siteaccess), or remove the key from the extension's settings/ file. The extension's own per-siteaccess folders do not help: they are in the siteaccess scope too, and the extension's settings/ beats them as well.

The per-site folders inside an extension

An extension can carry per-siteaccess settings, so that a whole site, with all its siteaccesses, is one folder:

DirectoryApplies to
extension/<ext>/settings/siteaccess/<sa>/one siteaccess
extension/<ext>/settings/override__<group>/every siteaccess whose name starts with <group>__ (for example shop__en, shop__de for the group shop)
extension/<ext>/settings/override/every siteaccess the extension owns

These are registered only for a siteaccess that has its folder extension/<ext>/settings/siteaccess/<sa>/; that folder is what makes the extension the owner. Details and an example are in Per-site settings inside extensions.

Placements: where did a value come from?

exp:ini where and the settings page name each file's placement:

PlacementFile
defaultsettings/site.ini
overridesettings/override/site.ini.append.php
extension:<ext>extension/<ext>/settings/site.ini.append.php
siteaccesssettings/siteaccess/<sa>/site.ini.append.php
ext-siteaccess:<ext>extension/<ext>/settings/siteaccess/<sa>/site.ini.append.php
ext-siteaccess-override:<ext>extension/<ext>/settings/override/site.ini.append.php
ext-siteaccess-override__<group>:<ext>extension/<ext>/settings/override__<group>/site.ini.append.php
injectedset by code at run time

Try it for a setting that many files touch:

./console exp:ini where design.ini/ExtensionSettings/DesignExtensions
./console exp:ini where site.ini/DesignSettings/SiteDesign -s <your siteaccess>

-s <siteaccess> shows the result as that siteaccess sees it.

Choosing the place for a change

You want to changePut it inScope word for exp:ini
Something for the whole installation, that differs per server (database, mail server, paths)settings/override/global
One site's look or languagethe siteaccess, or better your site extension's settings/siteaccess/<sa>/siteaccess:<sa> or extension:<ext>:siteaccess:<sa>
What your own extension needs everywhereextension/<yours>/settings/extension:<yours>
The behavior of someone else's extensionsettings/override/ or your own extension listed before itglobal, or extension:<yours>

Two rules keep this manageable:

  • Server-specific and secret values (database passwords, host names) go in settings/override/, which is never committed. Everything else can live in extensions under version control.
  • Never edit another extension's settings files. They are replaced when that extension updates. Override them.

Moving settings into an extension

exp:ini can move settings between scopes for you, keeping the value in effect:

./console exp:ini move site.ini/DesignSettings siteaccess:mysite extension:mysite_settings:siteaccess:mysite --dry-run
./console exp:ini move-all siteaccess:mysite extension:mysite_settings:siteaccess:mysite --create-extension --dry-run

move-all with --create-extension creates the target extension (extension.xml, ezinfo.php, settings/) if it does not exist, and --activate switches it on. Remove --dry-run when the shown result is what you want. The next chapters use this to build a site extension.

Become an Exponential Partner

Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.

Something wrong on this page? Report an error

Documentation license

This documentation is free documentation, licensed under the GNU Free Documentation License 1.3 or later.

Exponential Copyright © 1998-2026 Exponential Foundation and 7x