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