Skip to content

Usage

Settings: Usage

CiviCRM settings are used frequently, so most environments (PHP, Smarty, Javascript, etc) provide some mechanism to access them. This page will present examples of each.

Before you start, understand setting scope.

Before accessing a specific setting, you must be clear on the intended scope:

  • Domain: Most CiviCRM sites have a Domain record to capture system-level options. (In some advanced systems with multi-tenant services, there may be multiple Domains.)
  • Contact: Each Contact (user) can track some personalized preferences.

In general, most settings are defined at the domain-level, so we will prioritize that. For completeness, we will include some examples of contact-oriented settings.

PHP

When writting PHP code, the most convenient notations use the Civi facade. To update and read a typical domain setting, use:

// Update a setting
Civi::settings()->set('theme_backend', 'minetta');

// Retrieve a setting
print_r(Civi::settings()->get('theme_backend'));

// Revert a setting (to its default)
Civi::settings()->revert('theme_backend');

Alternatively for contact-level settings, call Civi::contactSettings() instead:.

// Update a setting
Civi::contactSettings()->set('activity_tab_filter', ...);

// Retrieve a setting
print_r(Civi::contactSettings()->get('activity_tab_filter'));

// Revert a setting (to its default)
Civi::contactSettings()->revert('activity_tab_filter');

Default Domain and Default Contact

By default, Civi::settings() will work with the current/active Domain. If you need to work with alternate domains, specify Civi::settings($domainsId).

Similarly, Civi::contactSettings() will work with the current/active Contact/User. If you need to work with alternate contacts, specify Civi::contactSettings($contactId).

APIv3 actions

The following api actions have been introduced into CiviCRM

  • civicrm_api3('setting', 'getfields', array());
  • civicrm_api3('setting', 'get', array());
  • civicrm_api3('setting', 'getvalue', array()); (see note)
  • civicrm_api3('setting', 'create', array());
  • civicrm_api3('setting', 'getdefaults', array());
  • civicrm_api3('setting', 'revert', array());
  • civicrm_api3('setting', 'fill', array());

Note

'getvalue' is not a pseudonym for get - it is intended for runtime whereas get is a heavier function intended for configuration

As with all CiviCRM API you can access it through your standard CLI tools e.g.

drush civicrm-api setting.create debug_enabled =1 userFrameworkLogging=1
drush civicrm-api setting.revert filters.group=localization domain_id = 3

Smarty / Template Layer

crmAPI will interact with settings but a specific option exists. This will access settings stored in $config or settings

{crmSetting name="search_autocomplete_count" group="Search Preferences"}
(Group is still required here but .... fixing that)

Multiple Domains

The settings api supports the following values for domain_id :

  • current_domain (default)
  • integer
  • array of integers
  • all

It is desirable to make this api handling of domain id part of the api layer for all api that involve domains.