Settings and INI for CMS developers #

This page is for developers who configure Exponential projects. All configuration is INI files read in layers, and knowing which layer wins is most of the job. The rule for a project: never edit the shipped files in settings/; put your values in your extension, and machine-specific values in settings/override/.

Contents #

1. The format
2. The scopes and who wins
3. Where a project's settings belong
4. exp:ini: read and change safely
5. Settings in the administration
6. Values that differ per machine
7. Reading settings in templates and PHP
8. Caches and workers

The format #

<?php /* #?ini charset="utf-8"?

[DesignSettings]
SiteDesign=exp_mysite
AdditionalSiteDesignList[]
AdditionalSiteDesignList[]=standard

[RegionalSettings]
TranslationSA[eng]=English
*/ ?>

Override files end in .ini.append.php and wrap their content in a PHP comment, so a web server that serves the file shows nothing. Name[] with no value clears an array before the next lines add to it; Name[key]=value sets a hash entry (How INI settings work).

The scopes and who wins #

After the shipped default in settings/, the kernel reads these directories, and a later file wins:

1. an extension's per-siteaccess folders (extension/<ext>/settings/siteaccess/<sa>/ and its override/),
2. settings/siteaccess/<sa>/,
3. extension/<ext>/settings/ of every active extension (an extension earlier in ActiveExtensions[] wins),
4. settings/override/.

Note that an extension's global settings are read after settings/siteaccess/<sa>/, so they beat it (Settings scopes and the order they win in).

Where a project's settings belong #

Keeping site settings inside your extension means the whole site is in one repository and a new machine needs only its settings/override/ (Siteaccess settings, Extension settings for builders).

exp:ini: read and change safely #

./console exp:ini get site.ini/DesignSettings/SiteDesign -s <siteaccess>      # the value in effect
./console exp:ini where site.ini/DesignSettings/SiteDesign -s <siteaccess>    # every file that sets it, in load order
./console exp:ini list site.ini/DebugSettings                                  # a block
./console exp:ini set site.ini/DebugSettings/DebugOutput enabled global --dry-run --allow-root-user
./console exp:ini add 'site.ini/ExtensionSettings/ActiveExtensions[]' exp_mysite global --allow-root-user

where answers "why is this value not what I set?" in one call. Writes keep a backup in var/backup/ini/, clear the INI cache, and accept --dry-run. Scopes: global, siteaccess:<sa>, extension:<ext>, extension:<ext>:siteaccess:<sa>; writing the shipped defaults is refused (The exp:ini command, exp:ini in the console).

Settings in the administration #

Setup > Ini settings (settings/view) shows the settings of each siteaccess with the file each value comes from, and can change values for administrators (The settings page, Settings in the admin). Changes made there land in files; copy the ones that belong to the project into your extension.

Values that differ per machine #

Database credentials, mail transports and host names differ between development, staging and live. Keep them in each machine's settings/override/, which is not committed and not copied between machines. A few things that must be known before the settings are read come from environment variables and config.php (Environment variables, Environment settings). Never commit secrets to a repository, and never copy settings/override/ from live to a development machine.

Reading settings in templates and PHP #

{ezini( 'SiteSettings', 'SiteName', 'site.ini' )|wash()}

<?php
$ini = eZINI::instance( 'exp_mysite.ini' );
$limit = $ini->hasVariable( 'ListSettings', 'Limit' ) ? (int)$ini->variable( 'ListSettings', 'Limit' ) : 10;

A settings file of your own (exp_mysite.ini) lives in your extension's settings/ and is read like the kernel's (The ezini operator, eZINI, Settings in an extension).

Caches and workers #

Settings are cached. After editing a file by hand:

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

--clear-tag=ini covers the global INI cache too. Velocity's workers keep settings in memory: restart Velocity after INI changes (./console exp:velocity restart --allow-root-user), and reload the PHP-FPM that serves the site for changes that affect loaded classes (Deploying a site).

Related pages #

• Siteaccesses and multisite
• Append files and safety
• Module 8: Settings and siteaccesses
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.