Siteaccesses and configuration #

This page is for engineers who need to reason about configuration: where a value comes from, why it differs between two sites of one installation, and how to keep secrets and machine-specific values out of version control. The full reference is The INI settings cascade and INI override directories and placements.

Contents #

1. INI files and eZINI
2. The order of the cascade
3. Siteaccesses
4. Environments, deployments and secrets
5. Finding where a value comes from
6. Rules for configuration changes

INI files and eZINI #

All configuration is INI files read through eZINI (lib/ezutils/classes/ezini.php). The defaults ship in settings/<file>.ini; overrides are named <file>.ini.append.php (the .php suffix keeps them from being served as text). Code reads a value with:

$value = eZINI::instance( 'site.ini' )->variable( 'SiteSettings', 'SiteName' );

No code in kernel/, lib/ or bin/ parses INI files itself. The merged result is cached as PHP arrays in the INI cache; after a settings change clear it with the tag, which covers both the per-siteaccess and the global INI cache:

php bin/php/ezcache.php --clear-tag=ini --allow-root-user

The order of the cascade #

Later wins:

Two consequences engineers trip over:

• The settings/ of an extension in ActiveExtensions[] wins over settings/siteaccess/<sa>/; that of an extension in ActiveAccessExtensions[] does not.
• settings/override/ wins over everything.

Extensions are switched on in site.ini [ExtensionSettings] ActiveExtensions[] (global) and ActiveAccessExtensions[] (per siteaccess); these two cannot be set from inside an extension. The order of extensions can follow their declared dependencies (Extension loading order).

Siteaccesses #

A siteaccess is a named configuration selected per request: a public site, the administration, a language version. eZSiteAccess (kernel/classes/ezsiteaccess.php) matches it from site.ini [SiteAccessSettings]:

Code takes the current siteaccess from eZSiteAccess::current() and never parses the URL itself. Host and language matching: Siteaccess host and language matching.

Environments, deployments and secrets #

Finding where a value comes from #

./console exp:ini where site.ini/SiteSettings/SiteName
./console exp:ini get site.ini/SiteSettings/SiteName

where lists every file that sets the value, in load order, and the value in effect; exp:ini also sets, adds and removes values in a chosen scope (exp:ini). On a running installation the administration shows the merged settings under Setup (The settings page).

Rules for configuration changes #

• A new setting gets its default in the shipped settings/<file>.ini with a comment above it, a safe default, a section on its feature page and a line in the changelog.
• New switches use enabled/disabled.
• Settings are written with ./console exp:ini or eZINI::save(), never by string replacement in a script.
• A new class referenced from a shipped INI file should be guarded with class_exists() in the kernel, because a Velocity worker started before the deploy does not know it (Deploying a change).

Related pages #

• Settings and INI files
• Settings scopes and their order
• Multi-site installations
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.