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  *
 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  * Create or update a setting.
 245  *
 246  * @param array $params
 247  *   Parameters as per getfields.
 248  *
 249  * @return array
 250  *   api result array
 251  *
 252  * @throws \API_Exception
 253  * @throws \CiviCRM_API3_Exception
 254  */
 255 function civicrm_api3_setting_create($params) {
 256   $domains = _civicrm_api3_setting_getDomainArray($params);
 257   $result = CRM_Core_BAO_Setting::setItems($params, $domains);
 258   return civicrm_api3_create_success($result, $params, 'Setting', 'create');
 259 }
 260
 261 /**
 262  * Metadata for setting create function.
 263  *
 264  * @param array $params
 265  *   Parameters as passed to the API.
 266  */
 267 function _civicrm_api3_setting_create_spec(&$params) {
 268   $params['domain_id'] = [
 269     'api.default' => 'current_domain',
 270     'title' => 'Setting Domain',
 271     'description' => 'if you do not pass in a domain id this will default to the current domain
 272       an array or "all" are acceptable values for multiple domains',
 273   ];
 274   $params['group'] = [
 275     'title' => 'Setting Group',
 276     'description' => 'if you know the group defining it will make the api more efficient',
 277   ];
 278 }
 279
 280 /**
 281  * Returns array of settings matching input parameters.
 282  *
 283  * @param array $params
 284  *   Array of one or more valid property_name=>value pairs.
 285  *
 286  * @return array
 287  *   Array of matching settings
 288  */
 289 function civicrm_api3_setting_get($params) {
 290   $domains = _civicrm_api3_setting_getDomainArray($params);
 291   $result = CRM_Core_BAO_Setting::getItems($params, $domains, CRM_Utils_Array::value('return', $params, []));
 292   return civicrm_api3_create_success($result, $params, 'Setting', 'get');
 293 }
 294
 295 /**
 296  * Metadata for setting create function.
 297  *
 298  * @param array $params
 299  *   Parameters as passed to the API.
 300  */
 301 function _civicrm_api3_setting_get_spec(&$params) {
 302   $params['domain_id'] = [
 303     'api.default' => 'current_domain',
 304     'title' => 'Setting Domain',
 305     'description' => 'if you do not pass in a domain id this will default to the current domain',
 306   ];
 307   $params['group'] = [
 308     'title' => 'Setting Group',
 309     'description' => 'if you know the group defining it will make the api more efficient',
 310   ];
 311 }
 312
 313 /**
 314  * Returns value for specific parameter.
 315  *
 316  * Function requires more fields than 'get' but is intended for
 317  * runtime usage & should be quicker
 318  *
 319  * @param array $params
 320  *   Array of one or more valid.
 321  *                       property_name=>value pairs.
 322  *
 323  * @return array
 324  *   API result array.
 325  */
 326 function civicrm_api3_setting_getvalue($params) {
 327   //$config = CRM_Core_Config::singleton();
 328   //if (isset($config->$params['name'])) {
 329   //  return $config->$params['name'];
 330   //}
 331   return CRM_Core_BAO_Setting::getItem(
 332     NULL,
 333     CRM_Utils_Array::value('name', $params),
 334     CRM_Utils_Array::value('component_id', $params),
 335     CRM_Utils_Array::value('default_value', $params),
 336     CRM_Utils_Array::value('contact_id', $params),
 337     CRM_Utils_Array::value('domain_id', $params)
 338   );
 339 }
 340
 341 /**
 342  * Metadata for setting create function.
 343  *
 344  * @param array $params
 345  *   Parameters as passed to the API.
 346  */
 347 function _civicrm_api3_setting_getvalue_spec(&$params) {
 348
 349   $params['group'] = [
 350     'title' => 'Settings Group',
 351     'api.required' => TRUE,
 352   ];
 353   $params['name'] = [
 354     'title' => 'Setting Name',
 355     'api.aliases' => ['return'],
 356   ];
 357   $params['default_value'] = [
 358     'title' => 'Default Value',
 359   ];
 360   $params['component_id'] = [
 361     'title' => 'Component Id',
 362   ];
 363   $params['contact_id'] = [
 364     'title' => 'Contact Id',
 365   ];
 366   $params['domain_id'] = [
 367     'title' => 'Setting Domain',
 368     'description' => 'if you do not pass in a domain id this will default to the current domain',
 369   ];
 370 }
 371
 372 /**
 373  * Converts domain input into an array.
 374  *
 375  * If an array is passed in this is used, if 'all' is passed
 376  * in this is converted to 'all arrays'
 377  *
 378  * Really domain_id should always be set but doing an empty check because at the moment
 379  * using crm-editable will pass an id & default won't be applied
 380  * we did talk about id being a pseudonym for domain_id in this api so applying it here.
 381  *
 382  * @param array $params
 383  *
 384  * @return array
 385  * @throws API_Exception
 386  */
 387 function _civicrm_api3_setting_getDomainArray(&$params) {
 388   if (empty($params['domain_id']) && isset($params['id'])) {
 389     $params['domain_id'] = $params['id'];
 390   }
 391
 392   if ($params['domain_id'] === 'current_domain') {
 393     $params['domain_id'] = CRM_Core_Config::domainID();
 394   }
 395
 396   if ($params['domain_id'] === 'all') {
 397     $domainAPIResult = civicrm_api('domain', 'get', ['version' => 3, 'return' => 'id']);
 398     if (isset($domainAPIResult['values'])) {
 399       $params['domain_id'] = array_keys($domainAPIResult['values']);
 400     }
 401     else {
 402       throw new API_Exception('All domains not retrieved - problem with Domain Get api call ' . $domainAPIResult['error_message']);
 403     }
 404   }
 405   if (is_array($params['domain_id'])) {
 406     $domains = $params['domain_id'];
 407   }
 408   else {
 409     $domains = [$params['domain_id']];
 410   }
 411   return $domains;
 412 }