CRM/Core/BAO/Setting.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | Copyright CiviCRM LLC. All rights reserved.                        |
   5  |                                                                    |
   6  | This work is published under the GNU AGPLv3 license with some      |
   7  | permitted exceptions and without any warranty. For full license    |
   8  | and copyright information, see https://civicrm.org/licensing       |
   9  +--------------------------------------------------------------------+
  10  */
  11
  12 /**
  13  *
  14  * @package CRM
  15  * @copyright CiviCRM LLC https://civicrm.org/licensing
  16  */
  17
  18 /**
  19  * BAO object for civicrm_setting table. This table is used to store civicrm settings that are not used
  20  * very frequently (i.e. not on every page load)
  21  *
  22  * The group column is used for grouping together all settings that logically belong to the same set.
  23  * Thus all settings in the same group are retrieved with one DB call and then cached for future needs.
  24  */
  25 class CRM_Core_BAO_Setting extends CRM_Core_DAO_Setting {
  26
  27   /**
  28    * Various predefined settings that have been migrated to the setting table.
  29    */
  30   const
  31     ADDRESS_STANDARDIZATION_PREFERENCES_NAME = 'Address Standardization Preferences',
  32     CAMPAIGN_PREFERENCES_NAME = 'Campaign Preferences',
  33     DEVELOPER_PREFERENCES_NAME = 'Developer Preferences',
  34     DIRECTORY_PREFERENCES_NAME = 'Directory Preferences',
  35     EVENT_PREFERENCES_NAME = 'Event Preferences',
  36     MAILING_PREFERENCES_NAME = 'Mailing Preferences',
  37     MAP_PREFERENCES_NAME = 'Map Preferences',
  38     CONTRIBUTE_PREFERENCES_NAME = 'Contribute Preferences',
  39     MEMBER_PREFERENCES_NAME = 'Member Preferences',
  40     MULTISITE_PREFERENCES_NAME = 'Multi Site Preferences',
  41     PERSONAL_PREFERENCES_NAME = 'Personal Preferences',
  42     SYSTEM_PREFERENCES_NAME = 'CiviCRM Preferences',
  43     URL_PREFERENCES_NAME = 'URL Preferences',
  44     LOCALIZATION_PREFERENCES_NAME = 'Localization Preferences',
  45     SEARCH_PREFERENCES_NAME = 'Search Preferences';
  46
  47   /**
  48    * Retrieve the value of a setting from the DB table.
  49    *
  50    * @param string|null $group
  51    *   The group name of the item (deprecated).
  52    * @param string $name
  53    *   (required) The name under which this item is stored.
  54    * @param int $componentID
  55    *   The optional component ID (so componenets can share the same name space).
  56    * @param string $defaultValue
  57    *   The default value to return for this setting if not present in DB.
  58    * @param int $contactID
  59    *   If set, this is a contactID specific setting, else its a global setting.
  60    *
  61    * @param int $domainID
  62    *
  63    * @return mixed
  64    *   The data if present in the setting table, else null
  65    */
  66   public static function getItem(
  67     $group,
  68     $name = NULL,
  69     $componentID = NULL,
  70     $defaultValue = NULL,
  71     $contactID = NULL,
  72     $domainID = NULL
  73   ) {
  74     /** @var \Civi\Core\SettingsManager $manager */
  75     $manager = \Civi::service('settings_manager');
  76     $settings = ($contactID === NULL) ? $manager->getBagByDomain($domainID) : $manager->getBagByContact($domainID, $contactID);
  77     if ($name === NULL) {
  78       CRM_Core_Error::deprecatedWarning("Deprecated: Group='$group'. Name should be provided.\n");
  79     }
  80     if ($componentID !== NULL) {
  81       CRM_Core_Error::deprecatedWarning("Deprecated: Group='$group'. Name='$name'. Component should be omitted\n");
  82     }
  83     if ($defaultValue !== NULL) {
  84       CRM_Core_Error::deprecatedWarning("Deprecated: Group='$group'. Name='$name'. Defaults should come from metadata\n");
  85     }
  86     return $name ? $settings->get($name) : $settings->all();
  87   }
  88
  89   /**
  90    * Get multiple items from the setting table.
  91    *
  92    * @param array $params
  93    *   (required) An api formatted array of keys and values.
  94    * @param array $domains Array of domains to get settings for. Default is the current domain
  95    * @param $settingsToReturn
  96    *
  97    * @return array
  98    */
  99   public static function getItems(&$params, $domains, $settingsToReturn) {
 100     $originalDomain = CRM_Core_Config::domainID();
 101     if (empty($domains)) {
 102       $domains[] = $originalDomain;
 103     }
 104     if (!empty($settingsToReturn) && !is_array($settingsToReturn)) {
 105       $settingsToReturn = [$settingsToReturn];
 106     }
 107
 108     $fields = $result = [];
 109     $fieldsToGet = self::validateSettingsInput(array_flip($settingsToReturn), $fields, FALSE);
 110     foreach ($domains as $domainID) {
 111       $result[$domainID] = [];
 112       foreach ($fieldsToGet as $name => $value) {
 113         $contactID = $params['contact_id'] ?? NULL;
 114         $setting = CRM_Core_BAO_Setting::getItem(NULL, $name, NULL, NULL, $contactID, $domainID);
 115         if (!is_null($setting)) {
 116           // we won't return if not set - helps in return all scenario - otherwise we can't indentify the missing ones
 117           // e.g for revert of fill actions
 118           $result[$domainID][$name] = $setting;
 119         }
 120       }
 121     }
 122     return $result;
 123   }
 124
 125   /**
 126    * Store an item in the setting table.
 127    *
 128    * @param mixed $value
 129    *   (required) The value that will be serialized and stored.
 130    * @param string $group
 131    *   The group name of the item (deprecated).
 132    * @param string $name
 133    *   (required) The name of the setting.
 134    * @param int $componentID
 135    *   The optional component ID (so componenets can share the same name space).
 136    * @param int $contactID
 137    * @param int $createdID
 138    *   An optional ID to assign the creator to. If not set, retrieved from session.
 139    *
 140    * @param int $domainID
 141    *
 142    * @throws \CRM_Core_Exception
 143    *
 144    * @deprecated - refer docs https://docs.civicrm.org/dev/en/latest/framework/setting/
 145    */
 146   public static function setItem(
 147     $value,
 148     $group,
 149     $name,
 150     $componentID = NULL,
 151     $contactID = NULL,
 152     $createdID = NULL,
 153     $domainID = NULL
 154   ) {
 155     CRM_Core_Error::deprecatedFunctionWarning('refer docs for correct methods https://docs.civicrm.org/dev/en/latest/framework/setting/');
 156
 157     /** @var \Civi\Core\SettingsManager $manager */
 158     $manager = \Civi::service('settings_manager');
 159     $settings = ($contactID === NULL) ? $manager->getBagByDomain($domainID) : $manager->getBagByContact($domainID, $contactID);
 160     $settings->set($name, $value);
 161   }
 162
 163   /**
 164    * Store multiple items in the setting table. Note that this will also store config keys
 165    * the storage is determined by the metdata and is affected by
 166    *  'name' setting's name
 167    *  'config_key' = the config key is different to the settings key - e.g. debug where there was a conflict
 168    *  'legacy_key' = rename from config or setting with this name
 169    *
 170    * @param array $params
 171    *   (required) An api formatted array of keys and values.
 172    * @param array|null $domains
 173    *
 174    * @throws API_Exception
 175    * @domains array an array of domains to get settings for. Default is the current domain
 176    * @return array
 177    */
 178   public static function setItems(&$params, $domains = NULL) {
 179     $domains = empty($domains) ? [CRM_Core_Config::domainID()] : $domains;
 180
 181     // FIXME: redundant validation
 182     // FIXME: this whole thing should just be a loop to call $settings->add() on each domain.
 183
 184     $fields = [];
 185     $fieldsToSet = self::validateSettingsInput($params, $fields);
 186
 187     foreach ($fieldsToSet as $settingField => &$settingValue) {
 188       if (empty($fields['values'][$settingField])) {
 189         CRM_Core_Error::deprecatedWarning('Deprecated Path: There is a setting (' . $settingField . ') not correctly defined. You may see unpredictability due to this. CRM_Core_Setting::setItems');
 190         $fields['values'][$settingField] = [];
 191       }
 192       self::validateSetting($settingValue, $fields['values'][$settingField]);
 193     }
 194
 195     foreach ($domains as $domainID) {
 196       Civi::settings($domainID)->add($fieldsToSet);
 197       $result[$domainID] = $fieldsToSet;
 198     }
 199
 200     return $result;
 201   }
 202
 203   /**
 204    * Gets metadata about the settings fields (from getfields) based on the fields being passed in
 205    *
 206    * This function filters on the fields like 'version' & 'debug' that are not settings
 207    *
 208    * @param array $params
 209    *   Parameters as passed into API.
 210    * @param array $fields
 211    *   Empty array to be populated with fields metadata.
 212    * @param bool $createMode
 213    *
 214    * @throws API_Exception
 215    * @return array
 216    *   name => value array of the fields to be set (with extraneous removed)
 217    */
 218   public static function validateSettingsInput($params, &$fields, $createMode = TRUE) {
 219     $ignoredParams = [
 220       'version',
 221       'id',
 222       'domain_id',
 223       'debug',
 224       'created_id',
 225       'component_id',
 226       'contact_id',
 227       'filters',
 228       'entity_id',
 229       'entity_table',
 230       'sequential',
 231       'api.has_parent',
 232       'IDS_request_uri',
 233       'IDS_user_agent',
 234       'check_permissions',
 235       'options',
 236       'prettyprint',
 237       // CRM-18347: ignore params unintentionally passed by API explorer on WP
 238       'page',
 239       'noheader',
 240       // CRM-18347: ignore params unintentionally passed by wp CLI tool
 241       '',
 242       // CRM-19877: ignore params extraneously passed by Joomla
 243       'option',
 244       'task',
 245     ];
 246     $settingParams = array_diff_key($params, array_fill_keys($ignoredParams, TRUE));
 247     $getFieldsParams = ['version' => 3];
 248     if (count($settingParams) == 1) {
 249       // ie we are only setting one field - we'll pass it into getfields for efficiency
 250       [$name] = array_keys($settingParams);
 251       $getFieldsParams['name'] = $name;
 252     }
 253     $fields = civicrm_api3('setting', 'getfields', $getFieldsParams);
 254     $invalidParams = (array_diff_key($settingParams, $fields['values']));
 255     if (!empty($invalidParams)) {
 256       throw new API_Exception(implode(',', array_keys($invalidParams)) . " not valid settings");
 257     }
 258     if (!empty($settingParams)) {
 259       $filteredFields = array_intersect_key($settingParams, $fields['values']);
 260     }
 261     else {
 262       // no filters so we are interested in all for get mode. In create mode this means nothing to set
 263       $filteredFields = $createMode ? [] : $fields['values'];
 264     }
 265     return $filteredFields;
 266   }
 267
 268   /**
 269    * Validate & convert settings input.
 270    *
 271    * @param mixed $value
 272    *   value of the setting to be set
 273    * @param array $fieldSpec
 274    *   Metadata for given field (drawn from the xml)
 275    * @param bool $convertToSerializedString
 276    *   Deprecated mode
 277    *
 278    * @return bool
 279    * @throws \API_Exception
 280    */
 281   public static function validateSetting(&$value, array $fieldSpec, $convertToSerializedString = TRUE) {
 282     // Deprecated guesswork - should use $fieldSpec['serialize']
 283     if ($convertToSerializedString && $fieldSpec['type'] == 'String' && is_array($value)) {
 284       $value = CRM_Core_DAO::VALUE_SEPARATOR . implode(CRM_Core_DAO::VALUE_SEPARATOR, $value) . CRM_Core_DAO::VALUE_SEPARATOR;
 285     }
 286     if (empty($fieldSpec['validate_callback'])) {
 287       return TRUE;
 288     }
 289     else {
 290       $cb = Civi\Core\Resolver::singleton()->get($fieldSpec['validate_callback']);
 291       if (!call_user_func_array($cb, array(&$value, $fieldSpec))) {
 292         throw new API_Exception("validation failed for {$fieldSpec['name']} = $value  based on callback {$fieldSpec['validate_callback']}");
 293       }
 294     }
 295   }
 296
 297   /**
 298    * Validate & convert settings input - translate True False to 0 or 1.
 299    *
 300    * @param mixed $value value of the setting to be set
 301    * @param array $fieldSpec Metadata for given field (drawn from the xml)
 302    *
 303    * @return bool
 304    * @throws \API_Exception
 305    */
 306   public static function validateBoolSetting(&$value, $fieldSpec) {
 307     if (!CRM_Utils_Rule::boolean($value)) {
 308       throw new API_Exception("Boolean value required for {$fieldSpec['name']}");
 309     }
 310     if (!$value) {
 311       $value = 0;
 312     }
 313     else {
 314       $value = 1;
 315     }
 316     return TRUE;
 317   }
 318
 319   /**
 320    * This provides information about the setting - similar to the fields concept for DAO information.
 321    * As the setting is serialized code creating validation setting input needs to know the data type
 322    * This also helps move information out of the form layer into the data layer where people can interact with
 323    * it via the API or other mechanisms. In order to keep this consistent it is important the form layer
 324    * also leverages it.
 325    *
 326    * Note that this function should never be called when using the runtime getvalue function. Caching works
 327    * around the expectation it will be called during setting administration
 328    *
 329    * Function is intended for configuration rather than runtime access to settings
 330    *
 331    * The following params will filter the result. If none are passed all settings will be returns
 332    *
 333    * @param int $componentID
 334    *   Id of relevant component.
 335    * @param array $filters
 336    * @param int $domainID
 337    * @param null $profile
 338    *
 339    * @return array
 340    *   the following information as appropriate for each setting
 341    *   - name
 342    *   - type
 343    *   - default
 344    *   - add (CiviCRM version added)
 345    *   - is_domain
 346    *   - is_contact
 347    *   - description
 348    *   - help_text
 349    */
 350   public static function getSettingSpecification(
 351     $componentID = NULL,
 352     $filters = [],
 353     $domainID = NULL,
 354     $profile = NULL
 355   ) {
 356     return \Civi\Core\SettingsMetadata::getMetadata($filters, $domainID);
 357   }
 358
 359   /**
 360    * @param $group
 361    * @param string $name
 362    * @param bool $system
 363    * @param int $userID
 364    * @param bool $localize
 365    * @param string $returnField
 366    * @param bool $returnNameANDLabels
 367    * @param null $condition
 368    *
 369    * @return array
 370    */
 371   public static function valueOptions(
 372     $group,
 373     $name,
 374     $system = TRUE,
 375     $userID = NULL,
 376     $localize = FALSE,
 377     $returnField = 'name',
 378     $returnNameANDLabels = FALSE,
 379     $condition = NULL
 380   ) {
 381     $optionValue = self::getItem($group, $name);
 382
 383     $groupValues = CRM_Core_OptionGroup::values($name, FALSE, FALSE, $localize, $condition, $returnField);
 384
 385     //enabled name => label require for new contact edit form, CRM-4605
 386     if ($returnNameANDLabels) {
 387       $names = $labels = $nameAndLabels = [];
 388       if ($returnField == 'name') {
 389         $names = $groupValues;
 390         $labels = CRM_Core_OptionGroup::values($name, FALSE, FALSE, $localize, $condition, 'label');
 391       }
 392       else {
 393         $labels = $groupValues;
 394         $names = CRM_Core_OptionGroup::values($name, FALSE, FALSE, $localize, $condition, 'name');
 395       }
 396     }
 397
 398     $returnValues = [];
 399     foreach ($groupValues as $gn => $gv) {
 400       $returnValues[$gv] = 0;
 401     }
 402
 403     if ($optionValue && !empty($groupValues)) {
 404       $dbValues = explode(CRM_Core_DAO::VALUE_SEPARATOR,
 405         substr($optionValue, 1, -1)
 406       );
 407
 408       if (!empty($dbValues)) {
 409         foreach ($groupValues as $key => $val) {
 410           if (in_array($key, $dbValues)) {
 411             $returnValues[$val] = 1;
 412             if ($returnNameANDLabels) {
 413               $nameAndLabels[$names[$key]] = $labels[$key];
 414             }
 415           }
 416         }
 417       }
 418     }
 419     return ($returnNameANDLabels) ? $nameAndLabels : $returnValues;
 420   }
 421
 422   /**
 423    * @param string $group
 424    *   Deprecated parameter
 425    * @param string $name
 426    * @param mixed $value
 427    * @param bool $system
 428    * @param int $userID
 429    * @param string $keyField
 430    *
 431    * @throws \CRM_Core_Exception
 432    *
 433    * @deprecated
 434    */
 435   public static function setValueOption(
 436     $group,
 437     $name,
 438     $value,
 439     $system = TRUE,
 440     $userID = NULL,
 441     $keyField = 'name'
 442   ) {
 443     CRM_Core_Error::deprecatedFunctionWarning('refer docs for correct methods https://docs.civicrm.org/dev/en/latest/framework/setting/');
 444     if (empty($value)) {
 445       $optionValue = NULL;
 446     }
 447     elseif (is_array($value)) {
 448       $groupValues = CRM_Core_OptionGroup::values($name, FALSE, FALSE, FALSE, NULL, $keyField);
 449
 450       $cbValues = [];
 451       foreach ($groupValues as $key => $val) {
 452         if (!empty($value[$val])) {
 453           $cbValues[$key] = 1;
 454         }
 455       }
 456
 457       if (!empty($cbValues)) {
 458         $optionValue = CRM_Core_DAO::VALUE_SEPARATOR . implode(CRM_Core_DAO::VALUE_SEPARATOR,
 459             array_keys($cbValues)
 460           ) . CRM_Core_DAO::VALUE_SEPARATOR;
 461       }
 462       else {
 463         $optionValue = NULL;
 464       }
 465     }
 466     else {
 467       $optionValue = $value;
 468     }
 469
 470     self::setItem($optionValue, $group, $name);
 471   }
 472
 473   /**
 474    * Check if environment is explicitly set.
 475    *
 476    * @param $setting
 477    *
 478    * @return bool
 479    */
 480   public static function isEnvironmentSet($setting): bool {
 481     CRM_Core_Error::deprecatedFunctionWarning('no alternative');
 482     $environment = CRM_Core_Config::environment();
 483     return $setting === 'environment' && $environment;
 484   }
 485
 486   /**
 487    * Check if job is able to be executed by API.
 488    *
 489    * @param $params
 490    *
 491    * @throws \CRM_Core_Exception
 492    */
 493   public static function isAPIJobAllowedToRun($params): void {
 494     $environment = CRM_Core_Config::environment(NULL, TRUE);
 495     if ($environment !== 'Production') {
 496       if (!empty($params['runInNonProductionEnvironment'])) {
 497         $mailing = Civi::settings()->get('mailing_backend_store');
 498         if ($mailing) {
 499           Civi::settings()->set('mailing_backend', $mailing);
 500         }
 501       }
 502       else {
 503         throw new CRM_Core_Exception(ts('Job has not been executed as it is a %1 (non-production) environment.', [1 => $environment]));
 504       }
 505     }
 506   }
 507
 508   /**
 509    * Setting Callback - On Change.
 510    *
 511    * Respond to changes in the "environment" setting.
 512    *
 513    * @param array $oldValue
 514    *   Value of old environment mode.
 515    * @param array $newValue
 516    *   Value of new environment mode.
 517    * @param array $metadata
 518    *   Specification of the setting (per *.settings.php).
 519    */
 520   public static function onChangeEnvironmentSetting($oldValue, $newValue, $metadata) {
 521     if ($newValue !== 'Production') {
 522       $mailing = Civi::settings()->get('mailing_backend');
 523       if ($mailing['outBound_option'] != CRM_Mailing_Config::OUTBOUND_OPTION_DISABLED) {
 524         Civi::settings()->set('mailing_backend_store', $mailing);
 525       }
 526       Civi::settings()->set('mailing_backend', ['outBound_option' => CRM_Mailing_Config::OUTBOUND_OPTION_DISABLED]);
 527       CRM_Core_Session::setStatus(ts('Outbound emails have been disabled. Scheduled jobs will not run unless runInNonProductionEnvironment=TRUE is added as a parameter for a specific job'), ts("Non-production environment set"), "success");
 528     }
 529     else {
 530       $mailing = Civi::settings()->get('mailing_backend_store');
 531       if ($mailing) {
 532         Civi::settings()->set('mailing_backend', $mailing);
 533       }
 534     }
 535   }
 536
 537 }