6.0.0-git
2018-12-10
Last Modified 2013-09-04 by Jan Schneider

Configuration files

All applications' configuration files are inside the applications' config/ directories. All configuration files are valid PHP files. This has the drawback that they are more difficult to edit, and that administrators might create invalid PHP code, leading to parsing errors and breaking the applications.

But there are several good reasons for making configuration files PHP code:

  • There is no overhead in parsing the files, they provide configuration data in a format that can be used in the applications immediately.
  • One can use the result of PHP expressions in configuration values, e.g. gettext strings (_("Some translated string")), or references ($_SERVER['SERVER_NAME'])
  • Experienced administrators with PHP knowledge can create lookup functions that return dynamic configuration values, e.g. $servers['host'] = lookup_host(); with lookup_host() being a function looking up the 'host' value from a database or LDAP directory depending on the user name.

There is a set of default configuration files that are mandatory for an application, or optional but consistently used across all applications:

  • conf.php: This is the main configuration file that contains global options for every application.
  • prefs.php: This file controls the available user preferences for the application, their default values, and also controls which preferences users can alter.
  • mime_drivers.php: This file controls local MIME drivers (aka MIME viewer) for the application, specifically what kinds of files are viewable and/or downloadable.
  • servers.php, backends.php, sources.php: If an application can connect to different servers, backends, or directories, these will be defined and configured here.

Normally, the configuration files have distributed examples with a .dist suffix appended to the file names. The prefs.php file for example comes distributed as prefs.php.dist. Applications are configured by copying e.g. prefs.php.dist to prefs.php and editing the configuration files with any text editor.

The only exception is currently the conf.php file, which no longer comes as a conf.php.dist file, but as a conf.xml file containing the available options and their default values as XML markup (see ConfXML). A graphical setup interface is created from this XML data that administrators can open and edit in their browsers. If they submit the configuration form, the PHP configuration files are created automatically, they no longer need to edited manually. This approach solves most of the drawbacks with PHP configuration files while keeping the good things:

  • The chances are much lower that administrators accidentally break the configuration files by creating invalid PHP code.
  • Configuration is much easier using a graphical interface.
  • The configuration files are still PHP code.
  • Administrators can still customize the configuration with their own PHP code.

This approach will be extended over other configuration files in the future.