Configuration
Exponential is configured with INI files. Every part of the system reads its settings from them: the database connection, the siteaccesses, the designs, the classes allowed in a folder, the image sizes, the cronjobs. The defaults ship with the system; your changes go into override files that an update never touches. This page explains how the files are found and combined; the pages below it describe siteaccesses, how a siteaccess is chosen and siteaccess settings in extensions.
The format
An INI file is made of blocks with settings. A setting is a single value or an array:
[SiteSettings] SiteName=My site [ExtensionSettings] ActiveExtensions[] ActiveExtensions[]=ezjscore ActiveExtensions[]=ezoe [RegionalSettings] TranslationSA[eng]=English
| Line | What it does |
|---|---|
| Name=value | Sets a single value; values read earlier no longer count. |
| Name[] | Empties the array: what earlier files added is dropped. |
| Name[]=value | Adds an element at the end of the array. |
| Name[key]=value | Sets the element key, replacing an earlier one with that key. |
| # text | A comment. |
The defaults are settings/<name>.ini, for example settings/site.ini. Your own files are named <name>.ini.append.php and wrap the settings in a PHP comment, so a browser that requests the file gets an empty page instead of your database password:
<?php /* #?ini charset="utf-8"? [SiteSettings] SiteName=My site */ ?>
Where settings are read from, and which file wins
Each INI file is read in layers, and a later layer wins. For a siteaccess named site, site.ini is read in this order:
| Order | Layer | Where |
|---|---|---|
| 1 | The defaults | settings/site.ini |
| 2 | An extension's settings for this siteaccess | extension/<ext>/settings/siteaccess/site/site.ini.append.php |
| 3 | The siteaccess | settings/siteaccess/site/site.ini.append.php |
| 4 | The active extensions | extension/<ext>/settings/site.ini.append.php |
| 5 | The global override | settings/override/site.ini.append.php |
So settings/override/ wins over everything, for every siteaccess: use it for what is the same everywhere (the database, mail, the active extensions). Put what belongs to one siteaccess (its design, languages, debug output) in settings/siteaccess/<name>/. Never change the files directly in settings/ or in a shipped extension's settings/: an update replaces them.
To see which file sets a value, and every file in the chain, ask the console or open Setup > Ini settings in the administration:
./console exp:ini where site.ini/SiteSettings/SiteName site ./console exp:ini set site.ini/SiteSettings/SiteName "My site" global --dry-run
The INI cache
The combined result of the layers is cached below var/. The settings page and exp:ini clear it when they save. After editing a file by hand, clear it yourself; a few settings (the database, the active extensions) are read by Exponential Velocity only when it starts, so it needs a restart too:
php bin/php/ezcache.php --clear-tag=ini --allow-root-user
The most used files
| File | Configures |
|---|---|
| site.ini | Siteaccesses, the database, designs, languages, mail, users, debugging, extensions |
| content.ini | Datatypes, versions, the top level nodes, custom tags, publishing |
| override.ini | Which template is used where (override rules) |
| design.ini | Design extensions, style sheets and scripts |
| image.ini | Image sizes (aliases) and converters |
| file.ini | File handling and clustering |
| module.ini | The modules and where they are found |
| cronjob.ini | The cronjob parts and their scripts |
| workflow.ini, shop.ini, collect.ini | Workflow events and triggers, the webshop, information collection |
Every setting with its default and an example is in the INI settings examples; Configuring Exponential 6.0 walks through a new installation's settings.
In this section
- Site management Siteaccesses: the faces of one installation, where they are defined and the settings that make one.
- Extension siteaccess settings Siteaccess settings inside an extension: where the files go and when they are read.
- Access methods How a request is matched to a siteaccess: by path, host, host and path, port or server variable.
- Discussion: Override means override? A discussion kept from the eZ Publish documentation site; the current page is Configuration.
Contributors
- Balazs Halasy
- Geir Arne Waaler
- Vincent Commenter
- Claudia Kosny Commenter
- Piotrek Karaś
- Graham Brookins Updated Maintainer
Comments (3 historical)
Written by readers of the earlier documentation sites, kept as they were.
Override means override?
Vincent ·
I mean, exponential takes the default configuration file and if exists override it with the properties found in the corresponding override file.
We only need to override the properties we want to change, not copy the whole file in the overide directory and change some properties.
It's a question.
Re: Override means override?
Claudia Kosny ·
Yes, you only need the properties you want to change in your override files, EZ will take the other ones from the default files (or the global override files).
Ini array handling
Piotrek Karas ·
It's easy to test on your own, but still could be helpful for some people to know, that: