Skip to content

Usage

Home > Developer Guide > Framework > Settings

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.

!!! tip "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 `Domain`s.)
* __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');

!!! tip "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.