3 +--------------------------------------------------------------------+
4 | CiviCRM version 4.7 |
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2015 |
7 +--------------------------------------------------------------------+
8 | This file is a part of CiviCRM. |
10 | CiviCRM is free software; you can copy, modify, and distribute it |
11 | under the terms of the GNU Affero General Public License |
12 | Version 3, 19 November 2007 and the CiviCRM Licensing Exception. |
14 | CiviCRM is distributed in the hope that it will be useful, but |
15 | WITHOUT ANY WARRANTY; without even the implied warranty of |
16 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
17 | See the GNU Affero General Public License for more details. |
19 | You should have received a copy of the GNU Affero General Public |
20 | License and the CiviCRM Licensing Exception along |
21 | with this program; if not, contact CiviCRM LLC |
22 | at info[AT]civicrm[DOT]org. If you have questions about the |
23 | GNU Affero General Public License or the licensing of CiviCRM, |
24 | see the CiviCRM license FAQ at http://civicrm.org/licensing |
25 +--------------------------------------------------------------------+
31 * @copyright CiviCRM LLC (c) 2004-2015
35 * BAO object for civicrm_setting table. This table is used to store civicrm settings that are not used
36 * very frequently (i.e. not on every page load)
38 * The group column is used for grouping together all settings that logically belong to the same set.
39 * Thus all settings in the same group are retrieved with one DB call and then cached for future needs.
41 class CRM_Core_BAO_Setting
extends CRM_Core_DAO_Setting
{
44 * Various predefined settings that have been migrated to the setting table.
47 ADDRESS_STANDARDIZATION_PREFERENCES_NAME
= 'Address Standardization Preferences',
48 CAMPAIGN_PREFERENCES_NAME
= 'Campaign Preferences',
49 DEVELOPER_PREFERENCES_NAME
= 'Developer Preferences',
50 DIRECTORY_PREFERENCES_NAME
= 'Directory Preferences',
51 EVENT_PREFERENCES_NAME
= 'Event Preferences',
52 MAILING_PREFERENCES_NAME
= 'Mailing Preferences',
53 MAP_PREFERENCES_NAME
= 'Map Preferences',
54 CONTRIBUTE_PREFERENCES_NAME
= 'Contribute Preferences',
55 MEMBER_PREFERENCES_NAME
= 'Member Preferences',
56 MULTISITE_PREFERENCES_NAME
= 'Multi Site Preferences',
57 PERSONAL_PREFERENCES_NAME
= 'Personal Preferences',
58 SYSTEM_PREFERENCES_NAME
= 'CiviCRM Preferences',
59 URL_PREFERENCES_NAME
= 'URL Preferences',
60 LOCALIZATION_PREFERENCES_NAME
= 'Localization Preferences',
61 SEARCH_PREFERENCES_NAME
= 'Search Preferences';
64 * Retrieve the value of a setting from the DB table.
66 * @param string $group
67 * (required) The group name of the item.
69 * (required) The name under which this item is stored.
70 * @param int $componentID
71 * The optional component ID (so componenets can share the same name space).
72 * @param string $defaultValue
73 * The default value to return for this setting if not present in DB.
74 * @param int $contactID
75 * If set, this is a contactID specific setting, else its a global setting.
77 * @param int $domainID
80 * The data if present in the setting table, else null
82 public static function getItem(
90 /** @var \Civi\Core\SettingsManager $manager */
91 $manager = \Civi
::service('settings_manager');
92 $settings = ($contactID === NULL) ?
$manager->getBagByDomain($domainID) : $manager->getBagByContact($domainID, $contactID);
95 CRM_Core_Error
::debug_log_message("Deprecated: Group='$group'. Name should be provided.\n");
97 if ($componentID !== NULL) {
98 CRM_Core_Error
::debug_log_message("Deprecated: Group='$group'. Name='$name'. Component should be omitted\n");
100 if ($defaultValue !== NULL) {
101 CRM_Core_Error
::debug_log_message("Deprecated: Group='$group'. Name='$name'. Defaults should come from metadata\n");
104 return $name ?
$settings->get($name) : $settings->all();
108 * Store multiple items in the setting table.
110 * @param array $params
111 * (required) An api formatted array of keys and values.
112 * @param array $domains Array of domains to get settings for. Default is the current domain
113 * @param $settingsToReturn
117 public static function getItems(&$params, $domains = NULL, $settingsToReturn) {
118 $originalDomain = CRM_Core_Config
::domainID();
119 if (empty($domains)) {
120 $domains[] = $originalDomain;
122 if (!empty($settingsToReturn) && !is_array($settingsToReturn)) {
123 $settingsToReturn = array($settingsToReturn);
125 $reloadConfig = FALSE;
127 $fields = $result = array();
128 $fieldsToGet = self
::validateSettingsInput(array_flip($settingsToReturn), $fields, FALSE);
129 foreach ($domains as $domainID) {
130 if ($domainID != CRM_Core_Config
::domainID()) {
131 $reloadConfig = TRUE;
132 CRM_Core_BAO_Domain
::setDomain($domainID);
134 $config = CRM_Core_Config
::singleton($reloadConfig, $reloadConfig);
135 $result[$domainID] = array();
136 foreach ($fieldsToGet as $name => $value) {
137 $contactID = CRM_Utils_Array
::value('contact_id', $params);
138 $setting = CRM_Core_BAO_Setting
::getItem(NULL, $name, NULL, NULL, $contactID, $domainID);
139 if (!is_null($setting)) {
140 // we won't return if not set - helps in return all scenario - otherwise we can't indentify the missing ones
141 // e.g for revert of fill actions
142 $result[$domainID][$name] = $setting;
145 CRM_Core_BAO_Domain
::resetDomain();
151 * Store an item in the setting table.
153 * _setItem() is the common logic shared by setItem() and setItems().
155 * @param object $value
156 * (required) The value that will be serialized and stored.
157 * @param string $group
158 * (required) The group name of the item.
159 * @param string $name
160 * (required) The name of the setting.
161 * @param int $componentID
162 * The optional component ID (so componenets can share the same name space).
163 * @param int $contactID
164 * @param int $createdID
165 * An optional ID to assign the creator to. If not set, retrieved from session.
167 * @param int $domainID
169 public static function setItem(
178 /** @var \Civi\Core\SettingsManager $manager */
179 $manager = \Civi
::service('settings_manager');
180 $settings = ($contactID === NULL) ?
$manager->getBagByDomain($domainID) : $manager->getBagByContact($domainID, $contactID);
181 $settings->set($name, $value);
185 * Store multiple items in the setting table. Note that this will also store config keys
186 * the storage is determined by the metdata and is affected by
187 * 'name' setting's name
188 * 'config_key' = the config key is different to the settings key - e.g. debug where there was a conflict
189 * 'legacy_key' = rename from config or setting with this name
191 * _setItem() is the common logic shared by setItem() and setItems().
193 * @param array $params
194 * (required) An api formatted array of keys and values.
195 * @param null $domains
197 * @throws api_Exception
198 * @domains array an array of domains to get settings for. Default is the current domain
201 public static function setItems(&$params, $domains = NULL) {
202 $domains = empty($domains) ?
array(CRM_Core_Config
::domainID()) : $domains;
204 // FIXME: redundant validation
205 // FIXME: this whole thing should just be a loop to call $settings->add() on each domain.
208 $fieldsToSet = self
::validateSettingsInput($params, $fields);
210 foreach ($fieldsToSet as $settingField => &$settingValue) {
211 self
::validateSetting($settingValue, $fields['values'][$settingField]);
214 foreach ($domains as $domainID) {
215 Civi
::settings($domainID)->add($fieldsToSet);
216 $result[$domainID] = $fieldsToSet;
223 * Gets metadata about the settings fields (from getfields) based on the fields being passed in
225 * This function filters on the fields like 'version' & 'debug' that are not settings
227 * @param array $params
228 * Parameters as passed into API.
229 * @param array $fields
230 * Empty array to be populated with fields metadata.
231 * @param bool $createMode
233 * @throws api_Exception
235 * name => value array of the fields to be set (with extraneous removed)
237 public static function validateSettingsInput($params, &$fields, $createMode = TRUE) {
238 $group = CRM_Utils_Array
::value('group', $params);
240 $ignoredParams = array(
259 $settingParams = array_diff_key($params, array_fill_keys($ignoredParams, TRUE));
260 $getFieldsParams = array('version' => 3);
261 if (count($settingParams) == 1) {
262 // ie we are only setting one field - we'll pass it into getfields for efficiency
263 list($name) = array_keys($settingParams);
264 $getFieldsParams['name'] = $name;
266 $fields = civicrm_api3('setting', 'getfields', $getFieldsParams);
267 $invalidParams = (array_diff_key($settingParams, $fields['values']));
268 if (!empty($invalidParams)) {
269 throw new api_Exception(implode(',', array_keys($invalidParams)) . " not valid settings");
271 if (!empty($settingParams)) {
272 $filteredFields = array_intersect_key($settingParams, $fields['values']);
275 // no filters so we are interested in all for get mode. In create mode this means nothing to set
276 $filteredFields = $createMode ?
array() : $fields['values'];
278 return $filteredFields;
282 * Validate & convert settings input.
284 * @param mixed $value
285 * value of the setting to be set
286 * @param array $fieldSpec
287 * Metadata for given field (drawn from the xml)
290 * @throws \api_Exception
292 public static function validateSetting(&$value, $fieldSpec) {
293 if ($fieldSpec['type'] == 'String' && is_array($value)) {
294 $value = CRM_Core_DAO
::VALUE_SEPARATOR
. implode(CRM_Core_DAO
::VALUE_SEPARATOR
, $value) . CRM_Core_DAO
::VALUE_SEPARATOR
;
296 if (empty($fieldSpec['validate_callback'])) {
300 $cb = Civi\Core\Resolver
::singleton()->get($fieldSpec['validate_callback']);
301 if (!call_user_func_array($cb, array(&$value, $fieldSpec))) {
302 throw new api_Exception("validation failed for {$fieldSpec['name']} = $value based on callback {$fieldSpec['validate_callback']}");
308 * Validate & convert settings input - translate True False to 0 or 1.
310 * @param mixed $value value of the setting to be set
311 * @param array $fieldSpec Metadata for given field (drawn from the xml)
314 * @throws \api_Exception
316 public static function validateBoolSetting(&$value, $fieldSpec) {
317 if (!CRM_Utils_Rule
::boolean($value)) {
318 throw new api_Exception("Boolean value required for {$fieldSpec['name']}");
330 * This provides information about the setting - similar to the fields concept for DAO information.
331 * As the setting is serialized code creating validation setting input needs to know the data type
332 * This also helps move information out of the form layer into the data layer where people can interact with
333 * it via the API or other mechanisms. In order to keep this consistent it is important the form layer
336 * Note that this function should never be called when using the runtime getvalue function. Caching works
337 * around the expectation it will be called during setting administration
339 * Function is intended for configuration rather than runtime access to settings
341 * The following params will filter the result. If none are passed all settings will be returns
343 * @param int $componentID
344 * Id of relevant component.
345 * @param array $filters
346 * @param int $domainID
347 * @param null $profile
350 * the following information as appropriate for each setting
354 * - add (CiviCRM version added)
360 public static function getSettingSpecification(
366 return \Civi\Core\SettingsMetadata
::getMetadata($filters, $domainID);
371 * @param string $name
372 * @param bool $system
374 * @param bool $localize
375 * @param string $returnField
376 * @param bool $returnNameANDLabels
377 * @param null $condition
381 public static function valueOptions(
387 $returnField = 'name',
388 $returnNameANDLabels = FALSE,
391 $optionValue = self
::getItem($group, $name);
393 $groupValues = CRM_Core_OptionGroup
::values($name, FALSE, FALSE, $localize, $condition, $returnField);
395 //enabled name => label require for new contact edit form, CRM-4605
396 if ($returnNameANDLabels) {
397 $names = $labels = $nameAndLabels = array();
398 if ($returnField == 'name') {
399 $names = $groupValues;
400 $labels = CRM_Core_OptionGroup
::values($name, FALSE, FALSE, $localize, $condition, 'label');
403 $labels = $groupValues;
404 $names = CRM_Core_OptionGroup
::values($name, FALSE, FALSE, $localize, $condition, 'name');
408 $returnValues = array();
409 foreach ($groupValues as $gn => $gv) {
410 $returnValues[$gv] = 0;
413 if ($optionValue && !empty($groupValues)) {
414 $dbValues = explode(CRM_Core_DAO
::VALUE_SEPARATOR
,
415 substr($optionValue, 1, -1)
418 if (!empty($dbValues)) {
419 foreach ($groupValues as $key => $val) {
420 if (in_array($key, $dbValues)) {
421 $returnValues[$val] = 1;
422 if ($returnNameANDLabels) {
423 $nameAndLabels[$names[$key]] = $labels[$key];
429 return ($returnNameANDLabels) ?
$nameAndLabels : $returnValues;
434 * @param string $name
436 * @param bool $system
438 * @param string $keyField
440 public static function setValueOption(
451 elseif (is_array($value)) {
452 $groupValues = CRM_Core_OptionGroup
::values($name, FALSE, FALSE, FALSE, NULL, $keyField);
455 foreach ($groupValues as $key => $val) {
456 if (!empty($value[$val])) {
461 if (!empty($cbValues)) {
462 $optionValue = CRM_Core_DAO
::VALUE_SEPARATOR
. implode(CRM_Core_DAO
::VALUE_SEPARATOR
,
463 array_keys($cbValues)
464 ) . CRM_Core_DAO
::VALUE_SEPARATOR
;
471 $optionValue = $value;
474 self
::setItem($optionValue, $group, $name);
478 * Civicrm_setting didn't exist before 4.1.alpha1 and this function helps taking decisions during upgrade
482 public static function isUpgradeFromPreFourOneAlpha1() {
483 if (CRM_Core_Config
::isUpgradeMode()) {
484 $currentVer = CRM_Core_BAO_Domain
::version();
485 if (version_compare($currentVer, '4.1.alpha1') < 0) {