Skip to content

Settings

Introduction

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 theme
  • The folder which stores uploaded images
  • The URL which serves uploaded images

In this chapter, we examine the Settings subsystem, which is CiviCRM's standard tool for managing basic configuration. Key features:

  • Settings are essentially key-value pairs, as in: 
    Civi::settings()->set('theme_backend', 'minetta');
echo Civi::settings()->get('theme_backend');
  • Settings are used by the core application as well as add-on extensions.
  • Settings should be declared in a *.setting.php file.
  • Settings can be configured through programmatic APIs, mandatory overrides, and web-based forms.
  • Most settings are defined broadly (at the Domain level), but some settings are defined individually (at the Contact level).

To get started with settings for a new extension, see Settings: Tutorial.

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 define(). (Example: CIVICRM_DSN)
  • 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 define(). (Example: CIVICRM_CRED_KEYS)

History

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 civicrm_setting table, $civicrm_settings global, and CRM_Core_BAO_Setting class. Migrated some settings data from civicrm_domain to civicrm_setting.
  • v4.2 – Added public Settings API. Included support for CRUD'ing data from multiple sources (civicrm_domain and civicrm_setting). Migrated more settings data from civicrm_domain to civicrm_setting.
  • v4.3 to v4.6 – Incrementally migrate more settings data.
  • v4.7 – Added Civi::settings() and refactored init system. Finished migrating data from civicrm_domain to civicrm_setting.
  • v5.7 - Added Civi::contactSettings() as a facade to allow for managing of Contact Settings rather than domain level settings.
  • v5.8 - Added CRM_Admin_Form_Generic to create UI based solely on metadata.
  • v5.21 - CRM_Contact_BAO_Setting::setItem() will now emit deprecation warnings. Use Civi::settings(), Civi::contactSettings(), or the Setting API instead.
  • v5.33 - Tighten standards for well-defined settings
  • v5.68 - Added setting-admin@1 mixin directly to civicrm-core.
  • v5.79 - Added support for environmental settings (is_env_loadable).