INI configuration options are stored in both the config/config.ini.php and config/global.ini.php files.
global.ini.php contains default option values and is a file distributed with Matomo's codeconfig.ini.php contains the user configuration: it lets users override the default values. This file is not distributed with Matomo's code as it is customized by every user.Plugins and other code can access and modify INI config options using the Piwik\Config singleton.
To learn more about individual configuration options, read the documentation in global.ini.php.
The INI config options are grouped into different sections. Sections are declared in the INI configuration with surrounding brackets, for example:
[MySection]
my_config_value = 1
An option can be used to store multiple items by appending [] to the name and setting it more than once, for example:
[MySection]
myarray[] = 1
myarray[] = 2
myarray[] = 3
Note: When overriding a global configuration value in your config.ini.php file, the option needs to go into the same section as in the global config file.
If you don't have the section in your config file yet, you need to add it as well. Only that way the custom option value will be picked up by the config system.
The Config singleton allows PHP code to access whole configuration sections. They are accessed as if they were named public fields of the Config singleton.
For example, the following code will output every config option in the [General] section:
for (Config::getInstance()->General as $name => $value) {
echo "Option $name == " . print_r($value, true);
}
Configuration options can be modified in memory through the Config singleton in the same way they are set:
Config::getInstance()->Development['disable_merged_assets'] = 1;
To persist these changes, so they will appear in the INI files, call the forceSave() method:
Config::getInstance()->forceSave();
You can add new configs to Config::getClientSideOptions() and these configurations will then be accessible using JavaScript as part of the piwik.config object. When exposing a config you want to double check to not expose any configs that shouldn't be visible by everyone (publicly). Any configuration value will be visible to everyone through the HTML eg on the login screen etc. Also depending on the value you might want to enforce a certain type for the config. For example if the config is supposed to be an integer then it would be good to convert it to an integer just in case it is a string etc.
Plugins cannot add new configuration options. If you are creating a core contribution and want to add a new INI option, you can simply add the option and its default value to global.ini.php.
If you want to make your plugin configurable, create a Plugin Setting.
It's best practice to not start a configuration's name with disable_ but rather use enable_. For example, disable_processing_unique_visitors_range = 0 is slightly harder to read for non-technical users in comparison to enable_processing_unique_visitors_range = 1. Note that a boolean configuration doesn't have to start with enable_. Some settings might not use it, for example assume_secure_protocol = 0/1, multi_server_environment = 0/1, or force_ssl = 0/1.
For example, force_ssl = 1 is a boolean value in the configuration.
By convention, we check whether a feature is enabled by comparing
the setting against the value 1 like this:
if ( \Piwik\Config::getInstance()->General['setting'] == 1) {
}
This is currently not consistent throughout the code base as some places compared the value as a boolean like below (not recommended):
if ( \Piwik\Config::getInstance()->General['setting']) {
}
It was suggested that we improve and clarify this in the future. We can't refactor the boolean checks to compare against 1 as it would be a breaking change since it would mean if someone configures for example 2 then it would no longer be interpreted as enabled.
Please note when someone configures setting = on or
setting = yes then their value gets converted in the code
to 1 as well. The values off and no will be converted
to 0.