Applications like CiviCRM often need to be configured with a series of small, local options. For example, you might configure:
- The default language
- The default text-editor
- The folder which stores uploaded images
- The URL which serves uploaded images
In the pages of this chapter, we examine the Settings subsystem, which is CiviCRM's standard tool for managing configuration. Each setting
is declared in a
*.setting.php file. Settings can be configured through the web UI, the programmatic APIs, and the
Settings are used by the core application as well as add-on extensions. Settings are largely the same in both contexts, but there are some tips for Settings in the core application and tips for Settings in an extension.
Do all configuration options need to be stored as Settings?
Settings are ideal for many kinds of configuration, but there are some important exceptions:
- The Settings are only suited to simple key-value pairs. Some configurations require richer options. For example, a site-builder might configure Dedupe Rules and Relationship Types; these require their own entities (with multiple instances and multiple fields).
- The Settings only work if the CiviCRM application is online. Some options must be configured before
the application starts. These may be configured via
- The Settings have simplistic permissioning. If there is a very sensitive option (such as an encryption key) which should never be
accessed via remote API, then this may be configured via
In early versions of CiviCRM, all settings were stored either in the
CRM_Core_Config object or else globally in civicrm.settings.php. v4.x introduced a more open "Settings" system. This documentation covers the new way of managing settings.
The "Settings" system developed incrementally:
- v4.1 – Added
CRM_Core_BAO_Settingclass. Migrated some settings data from
- v4.2 – Added public Settings API. Included support for CRUD'ing data from multiple sources (
civicrm_setting). Migrated more settings data from
- v4.3 to v4.6 – Incrementally migrate more settings data.
- v4.7 – Added
Civi::settings()and refactored init system. Finished migrating data from
- v5.7 - Added
Civi::contactSettings()as a facade to allow for managing of Contact Settings rather than domain level settings.
- v5.8 - Added Generic CiviCRM settings form.
- v5.21 -
CRM_Contact_BAO_Setting::setItem()will now emit deprecation warnings. Use
Civi::contactSettings(), or the Setting API instead.
- v5.33 - Tighten standards for well-defined settings