Settings and INI files in your application
This page is for application creators who make their application configurable. Exponential's settings are INI files in layers; your extension ships its defaults and installations override them without touching your code.
Contents
Your own INI file
Ship defaults in extension/expdemo/settings/expdemo.ini (a new file of your own) and document every key there:
#?ini charset="utf-8"?
# Settings of the expdemo extension.
[ListSettings]
# How many items the latest view shows when no limit is given
DefaultLimit=10
# Class identifiers listed
ClassList[]
ClassList[]=articleChanges to other INI files (site.ini, module.ini, content.ini ...) go in *.ini.append.php files of your
extension, which wrap the content in a PHP comment so the web server never shows them:
[ModuleSettings]
ExtensionRepositories[]=expdemo
*/ ?>The layers
After settings/<file>.ini (the kernel's defaults), eZINI::overrideDirs() reads the override directories scope by
scope: sa-extension, siteaccess, extension, override. A value is read in this order; the last one wins:
settings/<file>.ini, the kernel's defaultssa-extension:settings/of the extensions the siteaccess switches on inActiveAccessExtensions[]siteaccess: the per-siteaccess directories inside extensions (settings/siteaccess/<siteaccess>/, thensettings/override__<group>/andsettings/override/, read only for a siteaccess the extension has asettings/siteaccess/<siteaccess>/directory for; Per-site settings), then the installation'ssettings/siteaccess/<siteaccess>/extension:settings/of every extension inActiveExtensions[], so also the<file>.iniand<file>.ini.append.phpyour extension shipsoverride:settings/override/of the installation
So a value in an active extension's settings/ wins over the same value in settings/siteaccess/<siteaccess>/; only
settings/override/ wins over it, and that applies to every siteaccess. If a site must be able to set a key per
siteaccess, do not ship that key in your extension's settings/ file; give its default in code with hasVariable()
(below). Inside one layer, an extension listed earlier in ActiveExtensions[] wins over a later one.
./console exp:ini where <file>/<block>/<key> <siteaccess> prints the files in this order for one setting.
Arrays add up across layers; an empty Key[] line clears what came before.
Reading settings in PHP and templates
$ini = eZINI::instance( 'expdemo.ini' );
$limit = $ini->hasVariable( 'ListSettings', 'DefaultLimit' )
? (int)$ini->variable( 'ListSettings', 'DefaultLimit' )
: 10;
$classes = $ini->variable( 'ListSettings', 'ClassList' ); // an arrayIn templates: ezini( 'ListSettings', 'DefaultLimit', 'expdemo.ini' ). Always give a safe default when a key may be
missing.
Changing settings
exp:ini reads and writes every scope line by line, keeping comments
(Change settings from the command line):
./console exp:ini get expdemo.ini/ListSettings/DefaultLimit
./console exp:ini set expdemo.ini/ListSettings/DefaultLimit 20 global
./console exp:ini where expdemo.ini/ListSettings/DefaultLimit siteSetup > Settings shows and edits settings in the browser (Settings page).
Secrets
API keys, passwords and tokens never go into your extension's repository. Read them from a key the installation sets in
settings/override/<file>.ini.append.php (mode 0640, not committed), and fail with a clear message when it is empty.
Environment-specific values: Environment settings and secrets.
Caches
Settings are cached. After a change: php bin/php/ezcache.php --clear-tag=ini --allow-root-user (not --clear-id=ini,
which misses the global INI cache), and restart Velocity's workers (exp:velocity deploy).
Related pages
- Anatomy of an extension
- Console exp:ini
- INI files keep their comments
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
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.