Skip to content

Setting Reference

What is a Setting?

Applications like CiviCRM often need to be 'configured' with small bits of persistent data, which may be different for each installation. Examples are:

  • The url of the CiviCRM site.
  • The path on the server where the CiviCRM code lives
  • MySQL connection information
  • The primary language of the install.

Sites can configure the settings through the UI or put in overrides

This page describes the CiviCRM standard tool for managing these configuration settings – the 'Settings' system. As a developer, you'll want to understand this system so you can access CiviCRM 'core' settings (e.g. if you're sending out a system email, you'll want to set an appropriate From name and address). You may also want to use this system for storing and retrieving your own settings for your extension. If you're a Drupal developer, this system is analogous to the Drupal variables table and tools.

Not all configuration-type values need to use this system - in particular, if you need to store persistent data that changes frequently and/or may grow indefinitely in size, this may not be the right tool. For example: if you want to have a custom set of allowable values for your extension, you'll want to use the 'Option Group' system. If you want to temporarily cache a value for the duration of a session, then the Cache system is the right tool. And if you're saving persistent data that may grow indefinitely over time, you'll want to look into creating and managing your own tables.


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.

In this chapter you can explore the following aspects of the settings framework

  • Properties - Properties that can be used as part of settings metadata array
  • Usage - How to access and store data for defined civicrm settings in the system provided by core or an extension
  • Extension Settings - This details on how extension authors can added settings to their extension and how to make a settings page show in the user interface
  • Core Settings - This covers how to add a new setting to civicrm core.