setting.md

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.

Background

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.

Settings Definition

Settings are defined in the /settings directory, in files ending with .settings.php

Each file consists of a php snippet which returns an array. Array keys are stings corresponding with each setting's name. Values are an array of metadata properties for that setting. Note that for radio buttons or similar the options will be retrieved if there is an option group of the same name. An example array is as follows:

  'remote_profile_submissions' => array(
    'group_name' => 'domain',
    'name' => 'remote_profile_submissions',
    'type' => 'Boolean',
    'quick_form_type' => 'YesNo',
    'default' => FALSE,
    'html_type' => 'radio',
    'add' => '4.7',
    'title' => 'Accept profile submissions from external sites',
    'is_domain' => 1,
    'is_contact' => 0,
    'description' => 'If enabled, CiviCRM will permit submissions from external sites to profiles. This is disabled by default to limit abuse.',
    'help_text' => NULL,
  ),

The Supported Properties for settings are:

property	Usage	Example Notes
group	?	Appears to correspond with the name of the file, doesn't that make it redundant?
group_name	Name of group this setting belongs to. These are defined as constants in the class CRM_Core_BAO_Setting	Uses a string & not a constant as it might be defined outside of core too (& the constants are particularly ugly for these). This has been deprecated as of 4.7. Since 4.7, the two main options are domain or contact. The older names such as CiviCRM Preferences are treated as aliases for domain or contact
name	Name of this setting	This is the same as the array key. Definitely redundant!
type	Data type	String, Array, Integer, Boolean
default	Default value	Value to use if setting is not set.
add	Version added to CiviCRM
quick_form_type	Widget type (admin form)	e.g YesNo, Element
html_type	Html type (admin form)	Used when quick_form_type is "Element".
html_attributes		size, style, class, etc.
title	Title (admin form)	note: do not use ts()
description	Description (admin form)	note: do not use ts()
help_text	Popup Help (admin form)	note: do not use ts()
validate_callback	Function to call for checking when submitted (admin form)	e.g CRM_Utils_Rule::url
on_change	Callback function when this setting is altered e.g when you enable a component or logging
is_domain	Domain setting	see civicrm_setting table
is_contact	Contact setting	see civicrm_setting table
prefetch	Legacy support - will store the setting in the $config object	We need to migrate away from this

Deprecated settings properties are :

property	Usage	Example Notes
config_only	Super legacy support - only store in the $config object (Removed/unnecessary in v4.7+)	And this
config_key	If the config key differs from the settings key (rarely used) (Removed/unnecessary in v4.7+)	used in conversions & for 'debug' where the config key name can't be used in the api
legacy_key	Used for conversions when upgrading and moving data from existing config array to being a setting (Removed/unnecessary in v4.7+)	This happens on upgrade and when civicrm_api3('system','flush') is called

Setting Storage and Retrieval