Developer Area/Config API

Mahara uses a Configuration API to store and access sitewide configuration parameters, kept in a key-value store.

How to read config settings

You can access config settings via the get_config() function or the $CFG global variable, depending on which coding style you prefer. Either way will give identical results.

Option 1: The get_config() function:

get_config('mysetting');

Option 2: The $CFG global variable:

global $CFG;
$CFG->mysetting;

How to write config settings

For changes which are stored in the database (such as those set via Mahara's admin screens), you can call set_config().

set_config('mysetting', $myvalue);

For changes which are stored in config.php, well, you'll have to edit your config.php file. There's not really any way around that.

Where config settings live

When you load up a page in Mahara and include "init.php" (as every Mahara page should), configuration parameters are loaded from these three sources, in this order. For the most part, configs in config.php override those from the config table, which override those from config-defaults.php. There are a few special configuration parameters which are calculated and set by init.php itself.

1. config.php: This is the main Mahara configuration file. Configuration parameters are set here by adding them as fields to a "$cfg" object. Some parameters must go here, including the database connection parameters, and some others which have been purposefully excluded from the Mahara admin screens for security purposes.
2. config table: This is a table in the Mahara database, where most configuration parameters are stored. They get put here by installation & upgrade scripts, and by users fiddling with the Mahara admin screens.
3. config-defaults.php: This is a file distributed with Mahara, which stores the default values of many configuration parameters which advanced users may wish to override in config.php. It also serves to document all the configuration parameters which are not editable from the Mahara admin screens.

Some configs shouldn't be web-editable

Some config parameters are not exposed through the Mahara admin screens. These settings cannot be changed by logging in to Mahara as an administrator and making changes in the browser. Instead, they must be overridden by editing the config.php file. All such configuration parameters should be documented (and given a default value, if applicable) in the config-defaults.php file.

The first category of such parameters, is "advanced" or "experimental" features, which may break Mahara's functionality if they are enabled. Hiding these in the config.php file protects inexperienced admins from accidentally enabling them.

The second category of such parameters is security-sensitive configs. As part of a defense in depth security strategy, configuration parameters which could be used to escalate privileges or which are otherwise sensitive, should be limited to the config.php file. This way, even if an attacker manages to obtain Mahara web admin access, these configs will still be safe unless the attacker can also obtain additional privileges.

Plugin configs

Each plugin in Mahara also gets to store its own sitewide configuration options. These are quite similar to the core config values.

Read

Plugin configs should be obtained from the get_config_plugin() function.

get_config_plugin('artefact', 'blog', 'mysetting');

Unlike core configs, they should not be accessed directly via $CFG, because they are not loaded unless they are specifically asked for.

Write

The corresponding get_config_plugin() function.

set_config_plugin('artefact', 'blog', 'mysetting', $myvalue);

Where they live

1. *_config tables: Each plugin type has its own separate table for configs: arefact_config, block_config, etc.
2. config.php and config-defaults.php: Like site configs, plugin configs can be specified in the config.php and config-defaults.php files. A plugin config is written like this: "$cfg->plugin->{$plugintype}->{$pluginname}->{$configname}". Depending on your PHP logging settings, you will probably also need to put an "@" in front of the declaration to prevent warnings about undefined variables. For example, to set the "host" config for the search.elasticsearch plugin: "@$cfg->plugin->search->elasticsearch->host = '127.0.0.1';"

Plugin config settings get populated by plugin install and upgrade scripts, and by users navigating to to "Administration -> Extensions" and then clicking on the "Configuration" link next to an extension that has a config screen defined. (See the Plugin API for more details about that).