Overriding site.ini

If we edit directly into site.ini we might have several problems if we wish to upgrade to a new version later on. The file might be overwritten by the new install, or if we take a backup of our file first, we might loose new settings included in the newer release.
To avoid these problems we have an override system for the configuration file. In settings/override/ we create a file called site.ini.append or site.ini.append.php. You should always use site.ini.append.php and place the variables inside PHP-comments (/* and */) on a non-virtual host setup for security reasons.
All variables placed in this file would override the variables placed in the main site.ini file.

Typical content of settings/override/site.ini.append:

[DatabaseSettings]

User=nextgen

Password=nextgen

Database=nextgen

 

[SiteAccessSettings]

HostMatchType=map

HostMatchMapItems[]=www.johenrik.com;user

HostMatchMapItems[]=admin.johenrik.com;admin

MatchOrder=host

This configuration file sets the database settings and site access settings.

Configuration files

In the /settings directory you will find several files and directories.

The *.ini files directly under the directory settings/ are default configuration files and should not be changed. Use them to look up some explanations about configuration options, but don't change them.

The files in /settings/override can be used to override configuration parameters. They are always valid and override any settings from other configuration files. These are global settings.

The directories in /settings/siteaccess are for different siteaccess rules. E.g. /settings/siteaccess/user is for the user site while /settings/siteaccess/admin is for the admin site. The files in /settings/siteaccess/[directory] are special settings that only count for that siteaccess method (e.g. a certain language or a different design). They get overridden by the /settings/override parameters, but they override the default parameters.

The configuration files are read in this order:

1. /settings/site.ini
2. /settings/siteaccess/[directory]/site.ini.append
3. /settings/override/site.ini.append.php

This means that settings in [3] override [2] which override [1]. If you want to change configuration settings for different siteaccess setups then create new directories under /settings/siteaccess and change them there (also remember to put those new siteaccess rules in /settings/override/site.ini.append.php).

It sounds complicated, but it's actually easy, logical, and makes sense. It also makes upgrades simpler, if you stick to this.