Configuration: INI files instead of YAML, PHP arrays or .env #

This page is for developers who configure an application in YAML, PHP arrays, settings.py or application.properties. All configuration of Exponential is in INI files, read through eZINI (lib/ezutils/classes/ezini.php). The defaults ship in settings/<file>.ini; everything you change lives in layers above them, so updates never overwrite your settings.

Contents #

1. Files and blocks
2. The layers and their order
3. Arrays
4. Reading settings
5. Changing settings
6. Caches
7. Compared with other frameworks

Files and blocks #

Each concern has a file (site.ini, content.ini, module.ini, design.ini, override.ini, rest.ini, velocity.ini ...), each file has blocks ([DatabaseSettings]), each block has keys. Files you add in a layer are named <file>.ini.append.php and wrap their content in a PHP comment, so the web server never shows them:

<?php /* #?ini charset="utf-8"?
[DebugSettings]
DebugOutput=enabled
*/ ?>

Your extension can also ship a file of its own, extension/expdemo/settings/expdemo.ini, with every key documented (Settings and INI files in your application).

The layers and their order #

eZINI reads the default file, then the override directories in this order, a later file winning (The INI settings cascade):

Note the order: an extension's global settings/ wins over settings/siteaccess/<siteaccess>/, and settings/override/ wins over everything. A value meant for one siteaccess only therefore belongs in a siteaccess directory of an extension or in settings/siteaccess/, not in an extension's global settings. The full reference is INI override directories and placements. With EXP_ENV set, each file can also have an environment variant read right after it (Environments and secrets).

Extensions are switched on in site.ini [ExtensionSettings] ActiveExtensions[] (global) and ActiveAccessExtensions[] (per siteaccess); these two cannot be set from inside an extension.

Arrays #

Keys ending in [] are arrays and add up across layers. An empty Key[] line clears what came before, so a layer can replace a list instead of extending it:

[RequestRuleSettings]
RuleList[]
RuleList[]=system_url_full_view_to_alias

Associative entries are written Implementation[<class>]=<subclass>.

Reading settings #

$ini = eZINI::instance( 'expdemo.ini' );
$limit = $ini->hasVariable( 'ListSettings', 'DefaultLimit' )
    ? (int)$ini->variable( 'ListSettings', 'DefaultLimit' )
    : 10;
$classes = $ini->variable( 'ListSettings', 'ClassList' );   // an array

In templates: ezini( 'ListSettings', 'DefaultLimit', 'expdemo.ini' ). Values are strings; cast them, and give a safe default when a key may be missing. Never parse INI files yourself.

Changing settings #

./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 site

exp:ini where lists every file that sets a value for a siteaccess, which answers "why is this value not the one I wrote" in seconds (Change settings from the command line). Setup > Settings shows and edits settings in the browser.

Caches #

Settings are cached. After a change: php bin/php/ezcache.php --clear-tag=ini (not --clear-id=ini, which misses the global INI cache), and restart Velocity's workers with ./console exp:velocity deploy, because the workers keep the settings they loaded.

Compared with other frameworks #

There is no expression language, no service parameters and no typed configuration tree: a key is a string or an array of strings.

Related pages #

• Settings and INI files in your application
• Console exp:ini
• Settings page
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.