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