api/v3/Setting.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 5                                                  |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2019                                |
   7  +--------------------------------------------------------------------+
   8  | This file is a part of CiviCRM.                                    |
   9  |                                                                    |
  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.   |
  13  |                                                                    |
  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.        |
  18  |                                                                    |
  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  +--------------------------------------------------------------------+
  26  */
  27
  28 /**
  29  * This api exposes CiviCRM configuration settings.
  30  *
  31  * @package CiviCRM_APIv3
  32  */
  33
  34 /**
  35  * Get fields for setting api calls.
  36  *
  37  * @param array $params
  38  *
  39  * @return array
  40  */
  41 function civicrm_api3_setting_getfields($params) {
  42   if (!empty($params['action']) && strtolower($params['action']) == 'getvalue') {
  43     $result = array(
  44       'name' => array(
  45         'title' => 'name of setting field',
  46         'api.required' => 1,
  47         'type' => CRM_Utils_Type::T_STRING),
  48       'group' => array(
  49         'api.required' => 0,
  50         'title' => 'Setting Group',
  51         'description' => 'Settings Group. This is required if the setting is not stored in config',
  52         'type' => CRM_Utils_Type::T_STRING),
  53     );
  54     return civicrm_api3_create_success($result, $params, 'Setting', 'getfields');
  55   }
  56   if (!empty($params['name'])) {
  57     //am of two minds about special handling for 'name' as opposed to other filters - but is does make most common
  58     //usage really easy
  59     $params['filters']['name'] = $params['name'];
  60   }
  61   $result = CRM_Core_BAO_Setting::getSettingSpecification(
  62     CRM_Utils_Array::value('component_id', $params),
  63     CRM_Utils_Array::value('filters', $params, array()),
  64     CRM_Utils_Array::value('domain_id', $params, NULL),
  65     CRM_Utils_Array::value('profile', $params, NULL)
  66   );
  67   // find any supplemental information
  68   if (!empty($params['action'])) {
  69     $specFunction = '_civicrm_api3_setting_' . strtolower($params['action']) . '_spec';
  70     if (function_exists($specFunction)) {
  71       $specFunction($result);
  72     }
  73   }
  74   return civicrm_api3_create_success($result, $params, 'Setting', 'getfields');
  75 }
  76
  77 /**
  78  * Alter metadata for getfields functions.
  79  *
  80  * @param array $params
  81  */
  82 function _civicrm_api3_setting_getfields_spec(&$params) {
  83   $params['filters'] = array(
  84     'title' => 'Filters',
  85     'description' => 'Fields you wish to filter by e.g. array("group_name" => "CiviCRM Preferences")',
  86   );
  87   $params['component_id'] = array(
  88     'title' => 'Component ID',
  89     'description' => 'ID of relevant component',
  90   );
  91   $params['profile'] = array(
  92     'title' => 'Profile',
  93     'description' => 'Profile is passed through to hooks & added to cachestring',
  94   );
  95 }
  96
  97 /**
  98  * Return default values for settings.
  99  *
 100  * We will domain key this as it could vary by domain (ie. urls)
 101  * as we will be creating the option for a function rather than an value to be in the defaults
 102  * Note that is not in place as yet.
 103  *
 104  * @param array $params
 105  *
 106  * @return array
 107  * @throws \CiviCRM_API3_Exception
 108  * @throws \Exception
 109  */
 110 function civicrm_api3_setting_getdefaults(&$params) {
 111   $settings = civicrm_api3('Setting', 'getfields', $params);
 112   $domains = _civicrm_api3_setting_getDomainArray($params);
 113   $defaults = array();
 114   foreach ($domains as $domainID) {
 115     $defaults[$domainID] = array();
 116     foreach ($settings['values'] as $setting => $spec) {
 117       if (array_key_exists('default', $spec) && !is_null($spec['default'])) {
 118         $defaults[$domainID][$setting] = $spec['default'];
 119       }
 120     }
 121   }
 122   return civicrm_api3_create_success($defaults, $params, 'Setting', 'getfields');
 123 }
 124 /**
 125  * Metadata for Setting create function.
 126  *
 127  * @param array $params
 128  *   Parameters as passed to the API.
 129  */
 130 function _civicrm_api3_setting_getdefaults_spec(&$params) {
 131   $params['domain_id'] = array(
 132     'api.default' => 'current_domain',
 133     'description' => 'Defaults may differ by domain - if you do not pass in a domain id this will default to the current domain
 134       an array or "all" are acceptable values for multiple domains',
 135     'title' => 'Setting Domain',
 136   );
 137 }
 138
 139 /**
 140  * Get options for settings.
 141  *
 142  * @param array $params
 143  *
 144  * @return array
 145  * @throws \API_Exception
 146  */
 147 function civicrm_api3_setting_getoptions($params) {
 148   $specs = CRM_Core_BAO_Setting::getSettingSpecification();
 149
 150   if (empty($specs[$params['field']]) || empty($specs[$params['field']]['pseudoconstant'])) {
 151     throw new API_Exception("The field '" . $params['field'] . "' has no associated option list.");
 152   }
 153
 154   $pseudoconstant = $specs[$params['field']]['pseudoconstant'];
 155
 156   // It would be nice if we could leverage CRM_Core_PseudoConstant::get() somehow,
 157   // but it's tightly coupled to DAO/field. However, if you really need to support
 158   // more pseudoconstant types, then probably best to refactor it. For now, KISS.
 159   if (!empty($pseudoconstant['callback'])) {
 160     $values = Civi\Core\Resolver::singleton()->call($pseudoconstant['callback'], array());
 161     return civicrm_api3_create_success($values, $params, 'Setting', 'getoptions');
 162   }
 163   elseif (!empty($pseudoconstant['optionGroupName'])) {
 164     $keyColumn = 'value';
 165     if (!empty($pseudoconstant['keyColumn'])) {
 166       $keyColumn = $pseudoconstant['keyColumn'];
 167     }
 168     return civicrm_api3_create_success(
 169       CRM_Core_OptionGroup::values($pseudoconstant['optionGroupName'], FALSE, FALSE, TRUE, NULL, 'label', TRUE, FALSE, $keyColumn),
 170       $params, 'Setting', 'getoptions'
 171     );
 172   }
 173
 174   throw new API_Exception("The field '" . $params['field'] . "' uses an unsupported option list.");
 175 }
 176
 177 /**
 178  * Revert settings to defaults.
 179  *
 180  * @param array $params
 181  *
 182  * @return array
 183  * @throws \Exception
 184  */
 185 function civicrm_api3_setting_revert(&$params) {
 186   $defaults = civicrm_api('Setting', 'getdefaults', $params);
 187   $fields = civicrm_api('Setting', 'getfields', $params);
 188   $fields = $fields['values'];
 189   $domains = _civicrm_api3_setting_getDomainArray($params);
 190   $result = array();
 191   foreach ($domains as $domainID) {
 192     $valuesToRevert = array_intersect_key($defaults['values'][$domainID], $fields);
 193     if (!empty($valuesToRevert)) {
 194       $valuesToRevert['version'] = $params['version'];
 195       $valuesToRevert['domain_id'] = $domainID;
 196       // note that I haven't looked at how the result would appear with multiple domains in play
 197       $result = array_merge($result, civicrm_api('Setting', 'create', $valuesToRevert));
 198     }
 199   }
 200
 201   return civicrm_api3_create_success($result, $params, 'Setting', 'revert');
 202 }
 203
 204 /**
 205  * Alter metadata for getfields functions.
 206  *
 207  * @param array $params
 208  */
 209 function _civicrm_api3_setting_revert_spec(&$params) {
 210   $params['name'] = array(
 211     'title' => 'Name',
 212     'description' => 'Setting Name belongs to',
 213   );
 214   $params['component_id'] = array(
 215     'title' => 'Component ID',
 216     'description' => 'ID of relevant component',
 217   );
 218   $params['domain_id'] = array(
 219     'api.default' => 'current_domain',
 220     'description' => 'Defaults may differ by domain - if you do not pass in a domain id this will default to the current domain'
 221     . ' an array or "all" are acceptable values for multiple domains',
 222     'title' => 'Setting Domain',
 223   );
 224 }
 225
 226 /**
 227  * Revert settings to defaults.
 228  *
 229  * @param array $params
 230  *
 231  * @return array
 232  * @throws \CiviCRM_API3_Exception
 233  * @throws \Exception
 234  */
 235 function civicrm_api3_setting_fill(&$params) {
 236   $defaults = civicrm_api3('Setting', 'getdefaults', $params);
 237   $domains = _civicrm_api3_setting_getDomainArray($params);
 238   $result = array();
 239   foreach ($domains as $domainID) {
 240     $apiArray = array(
 241       'version' => $params['version'],
 242       'domain_id' => $domainID,
 243     );
 244     $existing = civicrm_api3('Setting', 'get', $apiArray);
 245     $valuesToFill = array_diff_key($defaults['values'][$domainID], $existing['values'][$domainID]);
 246     if (!empty($valuesToFill)) {
 247       $result = array_merge($result, civicrm_api('Setting', 'create', $valuesToFill + $apiArray));
 248     }
 249   }
 250   return civicrm_api3_create_success($result, $params, 'Setting', 'fill');
 251 }
 252
 253 /**
 254  * Alter metadata for getfields functions.
 255  *
 256  * @param array $params
 257  */
 258 function _civicrm_api3_setting_fill_spec(&$params) {
 259   $params['name'] = array(
 260     'title' => 'Name',
 261     'description' => 'Setting Name belongs to',
 262   );
 263   $params['component_id'] = array(
 264     'title' => 'Component ID',
 265     'description' => 'ID of relevant component',
 266   );
 267   $params['domain_id'] = array(
 268     'api.default' => 'current_domain',
 269     'title' => 'Setting Domain',
 270     'description' => 'Defaults may differ by domain - if you do not pass in a domain id this will default to the '
 271     . 'current domain, an array or "all" are acceptable values for multiple domains',
 272   );
 273 }
 274
 275 /**
 276  * Create or update a setting.
 277  *
 278  * @param array $params
 279  *   Parameters as per getfields.
 280  *
 281  * @return array
 282  *   api result array
 283  */
 284 function civicrm_api3_setting_create($params) {
 285   $domains = _civicrm_api3_setting_getDomainArray($params);
 286   $result = CRM_Core_BAO_Setting::setItems($params, $domains);
 287   return civicrm_api3_create_success($result, $params, 'Setting', 'create');
 288 }
 289
 290 /**
 291  * Metadata for setting create function.
 292  *
 293  * @param array $params
 294  *   Parameters as passed to the API.
 295  */
 296 function _civicrm_api3_setting_create_spec(&$params) {
 297   $params['domain_id'] = array(
 298     'api.default' => 'current_domain',
 299     'title' => 'Setting Domain',
 300     'description' => 'if you do not pass in a domain id this will default to the current domain
 301       an array or "all" are acceptable values for multiple domains',
 302   );
 303   $params['group'] = array(
 304     'title' => 'Setting Group',
 305     'description' => 'if you know the group defining it will make the api more efficient',
 306   );
 307 }
 308
 309 /**
 310  * Returns array of settings matching input parameters.
 311  *
 312  * @param array $params
 313  *   Array of one or more valid property_name=>value pairs.
 314  *
 315  * @return array
 316  *   Array of matching settings
 317  */
 318 function civicrm_api3_setting_get($params) {
 319   $domains = _civicrm_api3_setting_getDomainArray($params);
 320   $result = CRM_Core_BAO_Setting::getItems($params, $domains, CRM_Utils_Array::value('return', $params, array()));
 321   return civicrm_api3_create_success($result, $params, 'Setting', 'get');
 322 }
 323 /**
 324  * Metadata for setting create function.
 325  *
 326  * @param array $params
 327  *   Parameters as passed to the API.
 328  */
 329 function _civicrm_api3_setting_get_spec(&$params) {
 330   $params['domain_id'] = array(
 331     'api.default' => 'current_domain',
 332     'title' => 'Setting Domain',
 333     'description' => 'if you do not pass in a domain id this will default to the current domain',
 334   );
 335   $params['group'] = array(
 336     'title' => 'Setting Group',
 337     'description' => 'if you know the group defining it will make the api more efficient',
 338   );
 339 }
 340 /**
 341  * Returns value for specific parameter.
 342  *
 343  * Function requires more fields than 'get' but is intended for
 344  * runtime usage & should be quicker
 345  *
 346  * @param array $params
 347  *   Array of one or more valid.
 348  *                       property_name=>value pairs.
 349  *
 350  * @return array
 351  *   API result array.
 352  */
 353 function civicrm_api3_setting_getvalue($params) {
 354   //$config = CRM_Core_Config::singleton();
 355   //if (isset($config->$params['name'])) {
 356   //  return $config->$params['name'];
 357   //}
 358   return CRM_Core_BAO_Setting::getItem(
 359     NULL,
 360     CRM_Utils_Array::value('name', $params),
 361     CRM_Utils_Array::value('component_id', $params),
 362     CRM_Utils_Array::value('default_value', $params),
 363     CRM_Utils_Array::value('contact_id', $params),
 364     CRM_Utils_Array::value('domain_id', $params)
 365   );
 366 }
 367
 368 /**
 369  * Metadata for setting create function.
 370  *
 371  * @param array $params
 372  *   Parameters as passed to the API.
 373  */
 374 function _civicrm_api3_setting_getvalue_spec(&$params) {
 375
 376   $params['group'] = array(
 377     'title' => 'Settings Group',
 378     'api.required' => TRUE,
 379   );
 380   $params['name'] = array(
 381     'title' => 'Setting Name',
 382     'api.aliases' => array('return'),
 383   );
 384   $params['default_value'] = array(
 385     'title' => 'Default Value',
 386   );
 387   $params['component_id'] = array(
 388     'title' => 'Component Id',
 389   );
 390   $params['contact_id'] = array(
 391     'title' => 'Contact Id',
 392   );
 393   $params['domain_id'] = array(
 394     'title' => 'Setting Domain',
 395     'description' => 'if you do not pass in a domain id this will default to the current domain',
 396   );
 397 }
 398
 399 /**
 400  * Converts domain input into an array.
 401  *
 402  * If an array is passed in this is used, if 'all' is passed
 403  * in this is converted to 'all arrays'
 404  *
 405  * Really domain_id should always be set but doing an empty check because at the moment
 406  * using crm-editable will pass an id & default won't be applied
 407  * we did talk about id being a pseudonym for domain_id in this api so applying it here.
 408  *
 409  * @param array $params
 410  *
 411  * @return array
 412  * @throws \Exception
 413  */
 414 function _civicrm_api3_setting_getDomainArray(&$params) {
 415   if (empty($params['domain_id']) && isset($params['id'])) {
 416     $params['domain_id'] = $params['id'];
 417   }
 418
 419   if ($params['domain_id'] == 'current_domain') {
 420     $params['domain_id']    = CRM_Core_Config::domainID();
 421   }
 422
 423   if ($params['domain_id'] == 'all') {
 424     $domainAPIResult = civicrm_api('domain', 'get', array('version' => 3, 'return' => 'id'));
 425     if (isset($domainAPIResult['values'])) {
 426       $params['domain_id'] = array_keys($domainAPIResult['values']);
 427     }
 428     else {
 429       throw new Exception('All domains not retrieved - problem with Domain Get api call ' . $domainAPIResult['error_message']);
 430     }
 431   }
 432   if (is_array($params['domain_id'])) {
 433     $domains = $params['domain_id'];
 434   }
 435   else {
 436     $domains = array($params['domain_id']);
 437   }
 438   return $domains;
 439 }