Skip to content

Settings Properties

Settings Definition

Settings are defined by PHP files (settings/*.setting.php).

Each setting has a symbolic name. New settings should follow the convention of {topic}_{property_name}, though there are many legacy settings which pre-date the convention.

Example: Conventional names

Here are some example settings which comply with the current convention. Each one has a topical prefix and uses lower_snake_case.

  • acl_cache_refresh_mode
  • acl_financial_type
  • invoice_due_date
  • invoice_due_date_period
  • invoice_notes
  • invoice_prefix
Example: Legacy names

Prior to CiviCRM v5.53, there was no enforcement of a naming convention. Consequently, there are many non-compliant, pre-existing names. These have been retained for backward-compatibility. Do not emulate them when making new settings.

A few examples:

  • enable_innodb_fts (does not use topical prefix)
  • update_contribution_on_membership_type_change (does not use topical prefix)
  • imageUploadDir (uses camelCase instead of lower_snake_case)
  • imageUploadURL (uses camelCase instead of lower_snake_case)

Each file consists of a PHP snippet which returns an array. Array keys are strings corresponding with each setting's name. Values are an array of metadata properties for that setting. An example array is as follows:

  'remote_profile_submissions' => [
    'name' => 'remote_profile_submissions',
    'type' => 'Boolean',
    'default' => FALSE,
    'html_type' => 'radio',
    'add' => '4.7',
    'title' => ts('Accept profile submissions from external sites'),
    'is_domain' => 1,
    'is_contact' => 0,
    'description' => ts('If enabled, CiviCRM will permit submissions from external sites to profiles. This is disabled by default to limit abuse.'),
    'settings_pages' => ['remote' => ['weight' => 10]],
  ],

For a serialized setting an example would be 

  'deduper_resolver_custom_groups_to_skip' => [
    'name' => 'deduper_resolver_custom_groups_to_skip',
    'type' => 'String',
    'serialize' => CRM_Core_DAO::SERIALIZE_JSON,
    'is_domain' => 1,
    'description' => E::ts('Custom tables that should be completely ignored (generally calculated fields such as summary fields)'),
    'default' => [],
    'title' => E::ts('Custom tables to skip'),
    'help_text' => '',
    'html_type' => 'select',
    'html_attributes' => [
      'class' => 'crm-select2',
      'multiple' => 1,
    ],
    'settings_pages' => ['deduper' => ['weight' => 150]],
    'pseudoconstant' => [
      'callback' => 'CRM_Deduper_BAO_MergeConflict::getCustomGroups',
    ],
  ],

An example using an Option Group called test_options, which adds the settings to the extensions settings page at civicrm/setting/test

return [
  'test_profile_frequency' => [
    'name' => 'test_profile_frequency',
    'type' => 'String',
    'default' => NULL,
    'html_type' => 'select',
    'add' => '4.7',
    'title' => ts('Choose frequency'),
    'is_domain' => 0,
    'is_contact' => 0,
    'description' => ts('Choose your frequency'),
    'pseudoconstant' => [
      'optionGroupName' => 'test_options',
    ],
    'settings_pages' => ['test' => ['weight' => 10]],
  ],
 ];

Supported Properties

The Supported Properties for settings are:

property Usage Example Notes
name Name of this setting This is the same as the array key. Required
type Data type String, Integer, Boolean (Array is discouraged as current uses of it do not have full handling and String + a serialize key addresses most uses)
title Title (admin form) note: use ts() or E::ts() for extensions
description Description (admin form) note: use ts() or E::ts() for extensions
serialize define how an array of values are stored ie CRM_Core_DAO::SERIALIZE_JSON is recommended. Other constants exist on the CRM_Core_DAO class
default Default value Value to use if setting is not set.
add Version added to CiviCRM
html_type Html type (admin form) This is the preferred way to describe the html type as it is not quick form specific. It will be used it present. Syntax is lower case. e.g 'select', 'radio', 'checkboxes', 'checkbox', 'text', 'textarea', 'entity_reference
pseudoconstant Provides information to build a list of available options This is the preferred methodology for lists of options and currently supports either a callback - e.g ['callback' => 'CRM_Core_SelectValues::geoProvider'] or an option group name ['optionGroupName' => 'advanced_search_options']. The advanced_search_options would be changed to the name of your Option Group. When specifying an optionGroupName you can optionally specify keyColumn to return a column from civicrm_option_value to use as the key. By default the keyColumn is the value column. As of CiviCRM 5.25 arbitrary tables are also supported. The format is the same as that used for field pseudoconstants
options provides an array of available options This is not the preferred methodology but make make sense for very simple lists.
entity_reference_options extra data to pass when adding an entity reference e.g if the entity is not contact this make be needed as in ['entity' => 'group', 'select' => ['minimumInputLength' => 0]]
documentation_link Array of information to build the 'learn more' link 'page' is required, if on the wiki 'resource' is also needed - e.g 'documentation_link' => ['page' => 'Multi Site Installation', 'resource' => 'wiki'],
help_text Intended to populated. Popup Help (admin form) note: use ts(), not working as intended as of 5.8
html_attributes size, style, class, etc.
validate_callback A string, the name of a callback function to validate the setting value. The callback is fired whether the setting is updated via admin form or API. The callback should accept the proposed setting value as its only argument. It should return TRUE if the value is valid, otherwise FALSE. In the latter case the API request will fail (is_error will be set to 1 in the result). If the callback takes the value by reference, it can modify the setting value before it is saved -- it remains to be seen whether this is wise. Example: '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 Setting is_domain to 1 indicates that the setting applies to the entire installation (in single site mode) or to a single domain in multi-site mode. If is_domain is set to 1, then is_contact must be set to 0.
is_contact Contact setting Setting is_contact to 1 indicates that the setting applies to a single contact and can be different for each contact. If is_contact is set to 1, is_domain must be set to 0.
settings_pages Metadata for presentation on settings pages The key (or keys) are the last part of the url on the page the setting should be displayed on. Adding a weight provides sorting

Deprecated Properties

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
prefetch Legacy support - will store the setting in the $config object We need to migrate away from this
group none This is redundant now
group_name Name of group this setting belongs to. 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.
quick_form_type Widget type (admin form): YesNo, CheckBox, CheckBoxes, Select, EntityRef, ChainSelect Superseded by html_type.