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.

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).

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 instance configs

These are configuration parameters for individual instances of a plugin. Currently the only plugin type that supports this is the auth plugin type. Each auth instance has its own set of plugin instance configs.

• Read: get_config_plugin_instance($plugintype, $pluginid, $key);
• Write: set_config_plugin_instance($plugintype, $pluginname, $pluginid, $key, $value);

Institution configs

Institutions also have a lot of configuration options. As of Mahara 1.9, these settings can now be treated similarly to site and plugin configs.

Where they live

Institution configs are in two database tables:

• institution: Before the creation of the institution_config table, most institution settings went in this table. When new settings were created, a new column would be added to the table.
  • From now on, only required or heavily used institution settings should get a new column in the institution table.
• institution_config: All new institution configs that don't have a great reason to go in the institution table, should go here instead.

Read

The traditional way to access institution settings was either by directly querying the institution table, or by instantiating an Institution object:

The Old Way:

$inst = new Institution('schoolofrock');
$skinsenabled = $inst->skins;

Now, you can use the new get_config_institution() or get_configs_user_institution() method.

The get_config_institution() method is for retrieving the config from a single institution, by name.

$skinsenabled = get_config_institution('schoolofrock', 'skins');

The get_configs_user_institution() function is for retrieving the configurations of all the institutions that a user belongs to. Note that this returns an array of values, because it is possible for a Mahara user to belong to more than one institution. The code that calls this function will have to figure out what to do if the user belongs to institutions with different values. For instance, for the setting to enable skins, we decided that as long as a user belongs to at least one institution that has enabled skins, they should be able to use skins.

This function takes two arguments: The name of the key, and the id of the user to check. The userid argument is optional, and if left off it will retrieve the settings for the current user.

$skinsettings = get_config_user_institutions('skins');

$skinsenabled = false;
foreach ($skinsettings as $setting) {
    if ($setting) {
         $skinsenabled = true;
         break;
    }
}

Write

There is not yet a corresponding "set_config_institution()" method, because most existing institution settings are only altered in one place, the institution editing screen. So, institution configs for now must be edited using the Instititution class.

$inst = new Institution('schoolofrock');
$inst->theme = 'aqua';
$inst->lang = 'es';
$inst->commit();

Accessing configs from Dwoo templates

As of Mahara 1.8, you can use the {ifconfig} tag in a Dwoo template, to take conditional actions based on the value of a config setting. It acts much like the Dwoo {if} tag (and can be used with {else}). See the comments in lib/dwoo/mahara/plugins/block.ifconfig.php for full details. This tag is useful for config settings to enable/disable features (it was written to support the $cfg->skins setting, which enables or disables Page skins sitewide.)

Examples:
{ifconfig key=foo}bar{else}baz{/ifconfig}           : Same as if (get_config('foo')) { echo "bar"; } else { echo "baz"; }
{ifconfig key=foo plugintype=block pluginname=blog} : Uses get_config_plugin()
{ifconfig key=foo plugintype=block pluginid=12}     : Uses get_config_plugin_instance()

It can also take a compareTo tag. If present, the value of the config will be compared to it. The compareTo value can be a string, integer, true, false, or null.

Example: {ifconfig key=foo compareTo=false}
Same as: if (get_config('foo') == false) {