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

Specification: INI override directories and placements

This page is the reference for how eZINI finds and orders the files of one INI setting: the four scopes, the per-siteaccess directories inside extensions (added in January 2026, commits 124186d096 and fc1a2f0a91), the…

Download as PDF

Address: https://doc.exponential.earth/exphelp/viewer/specifications/6.0/ini-override-placements.md

On this page

Specification: INI override directories and placements

This page is the reference for how eZINI finds and orders the files of one INI setting: the four scopes, the per-siteaccess directories inside extensions (added in January 2026, commits 124186d096 and fc1a2f0a91), the placement names that say where a value came from, and the constants that change the search. Read it when a setting does not take the value you expect, or when you place per-site settings inside an extension. The task-oriented page is Per-site settings inside extensions.

In short

  • Files are read in scope order sa-extension, siteaccess, extension, override; a later file wins.
  • An extension can carry per-siteaccess settings in settings/siteaccess/<sa>/, settings/override__<group>/ and settings/override/.
  • ./console exp:ini reads and writes the same files, so it sees the same result as the site.

Scopes and order

eZINI keeps override directories in four scopes. eZINI::overrideDirs() merges them as sa-extension, siteaccess, extension, override. Files are parsed in that order, and a later file overrides an earlier one.

Inside a scope, a directory registered later with prependOverrideDir() stands earlier in the list and therefore has lower priority.

Per-siteaccess directories inside an extension

eZExtension::prependExtensionSiteAccesses() (lib/ezutils/classes/ezextension.php) registers these directories for an active siteaccess that an extension owns, in this call order:

Call orderDirectoryIdentifierScopePriority inside the scope
1extension/<ext>/settings/override/ext-siteaccess-override:<ext>siteaccesshighest of the three
2extension/<ext>/settings/override__<group>/ (only if the siteaccess name contains __; <group> is the part before it)ext-siteaccess-override:<ext>:__group:<group>siteaccessmiddle
3extension/<ext>/settings/siteaccess/<siteaccess>/the extension identifiersiteaccesslowest of the three

All three are registered only if extension/<ext>/settings/siteaccess/<siteaccess> exists (one file_exists call per active extension siteaccess).

Example

An extension site_shop owns the siteaccesses shop__en and shop__de. A setting both siteaccesses share goes in extension/site_shop/settings/override__shop/site.ini.append.php; a setting only for the German site goes in extension/site_shop/settings/siteaccess/shop__de/site.ini.append.php. The group directory is read only because extension/site_shop/settings/siteaccess/shop__de/ exists.

Placements

eZINI::findSettingPlacement() names where a setting came from, by the number of path segments of the file relative to the installation root:

SegmentsExample pathPlacement
2settings/site.inidefault
3settings/override/site.ini.append.phpoverride
4extension/<ext>/settings/site.ini.append.phpextension:<ext>
4settings/siteaccess/<sa>/site.ini.append.phpsiteaccess
5extension/<ext>/settings/override/site.ini.append.phpext-siteaccess-override:<ext>
5extension/<ext>/settings/override__<group>/site.ini.append.phpext-siteaccess-override__<group>:<ext>
6extension/<ext>/settings/siteaccess/<sa>/site.ini.append.phpext-siteaccess:<ext>
(injected)settings injected at run timeinjected

Constants and globals

NameWhereEffect
$GLOBALS['eZINI_CONFIG_CACHE_DIR']read by eZINI::loadCache()Directory of the compiled INI cache. When unset, eZINI sets it to its default, var/cache/ini/ relative to the installation. Set it before the first INI file is loaded to share one cache between projects of one installation
EXP_SITE_STRUCTURE_EZ_INI_OVERRIDE_DIR_LISTdefine() it as trueAfter the directories above are registered, every override directory of the scope extension that starts with extension/site_ and does not belong to the extension of the active siteaccess is removed from the list for this request

Compatibility

Without these directories and without the global, nothing changes: the call that registered settings/siteaccess/<sa>/ before is now one of three, in the same position relative to the other scopes.

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