Skip to content

Setting Reference

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 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 setting-overrides.

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 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 Generic CiviCRM settings form.
  • 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