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