api/v3/Setting.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 5                                                  |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2017                                |
   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     return civicrm_api3_create_success(
 165       CRM_Core_OptionGroup::values($pseudoconstant['optionGroupName'], FALSE, FALSE, TRUE),
 166       $params, 'Setting', 'getoptions'
 167     );
 168   }
 169
 170   throw new API_Exception("The field '" . $params['field'] . "' uses an unsupported option list.");
 171 }
 172
 173 /**
 174  * Revert settings to defaults.
 175  *
 176  * @param array $params
 177  *
 178  * @return array
 179  * @throws \Exception
 180  */
 181 function civicrm_api3_setting_revert(&$params) {
 182   $defaults = civicrm_api('Setting', 'getdefaults', $params);
 183   $fields = civicrm_api('Setting', 'getfields', $params);
 184   $fields = $fields['values'];
 185   $domains = _civicrm_api3_setting_getDomainArray($params);
 186   $result = array();
 187   foreach ($domains as $domainID) {
 188     $valuesToRevert = array_intersect_key($defaults['values'][$domainID], $fields);
 189     if (!empty($valuesToRevert)) {
 190       $valuesToRevert['version'] = $params['version'];
 191       $valuesToRevert['domain_id'] = $domainID;
 192       // note that I haven't looked at how the result would appear with multiple domains in play
 193       $result = array_merge($result, civicrm_api('Setting', 'create', $valuesToRevert));
 194     }
 195   }
 196
 197   return civicrm_api3_create_success($result, $params, 'Setting', 'revert');
 198 }
 199
 200 /**
 201  * Alter metadata for getfields functions.
 202  *
 203  * @param array $params
 204  */
 205 function _civicrm_api3_setting_revert_spec(&$params) {
 206   $params['name'] = array(
 207     'title' => 'Name',
 208     'description' => 'Setting Name belongs to',
 209   );
 210   $params['component_id'] = array(
 211     'title' => 'Component ID',
 212     'description' => 'ID of relevant component',
 213   );
 214   $params['domain_id'] = array(
 215     'api.default' => 'current_domain',
 216     'description' => 'Defaults may differ by domain - if you do not pass in a domain id this will default to the current domain'
 217     . ' an array or "all" are acceptable values for multiple domains',
 218     'title' => 'Setting Domain',
 219   );
 220 }
 221
 222 /**
 223  * Revert settings to defaults.
 224  *
 225  * @param array $params
 226  *
 227  * @return array
 228  * @throws \CiviCRM_API3_Exception
 229  * @throws \Exception
 230  */
 231 function civicrm_api3_setting_fill(&$params) {
 232   $defaults = civicrm_api3('Setting', 'getdefaults', $params);
 233   $domains = _civicrm_api3_setting_getDomainArray($params);
 234   $result = array();
 235   foreach ($domains as $domainID) {
 236     $apiArray = array(
 237       'version' => $params['version'],
 238       'domain_id' => $domainID,
 239     );
 240     $existing = civicrm_api3('Setting', 'get', $apiArray);
 241     $valuesToFill = array_diff_key($defaults['values'][$domainID], $existing['values'][$domainID]);
 242     if (!empty($valuesToFill)) {
 243       $result = array_merge($result, civicrm_api('Setting', 'create', $valuesToFill + $apiArray));
 244     }
 245   }
 246   return civicrm_api3_create_success($result, $params, 'Setting', 'fill');
 247 }
 248
 249 /**
 250  * Alter metadata for getfields functions.
 251  *
 252  * @param array $params
 253  */
 254 function _civicrm_api3_setting_fill_spec(&$params) {
 255   $params['name'] = array(
 256     'title' => 'Name',
 257     'description' => 'Setting Name belongs to',
 258   );
 259   $params['component_id'] = array(
 260     'title' => 'Component ID',
 261     'description' => 'ID of relevant component',
 262   );
 263   $params['domain_id'] = array(
 264     'api.default' => 'current_domain',
 265     'title' => 'Setting Domain',
 266     'description' => 'Defaults may differ by domain - if you do not pass in a domain id this will default to the '
 267     . 'current domain, an array or "all" are acceptable values for multiple domains',
 268   );
 269 }
 270
 271 /**
 272  * Create or update a setting.
 273  *
 274  * @param array $params
 275  *   Parameters as per getfields.
 276  *
 277  * @return array
 278  *   api result array
 279  */
 280 function civicrm_api3_setting_create($params) {
 281   $domains = _civicrm_api3_setting_getDomainArray($params);
 282   $result = CRM_Core_BAO_Setting::setItems($params, $domains);
 283   return civicrm_api3_create_success($result, $params, 'Setting', 'create');
 284 }
 285
 286 /**
 287  * Metadata for setting create function.
 288  *
 289  * @param array $params
 290  *   Parameters as passed to the API.
 291  */
 292 function _civicrm_api3_setting_create_spec(&$params) {
 293   $params['domain_id'] = array(
 294     'api.default' => 'current_domain',
 295     'title' => 'Setting Domain',
 296     'description' => 'if you do not pass in a domain id this will default to the current domain
 297       an array or "all" are acceptable values for multiple domains',
 298   );
 299   $params['group'] = array(
 300     'title' => 'Setting Group',
 301     'description' => 'if you know the group defining it will make the api more efficient',
 302   );
 303 }
 304
 305 /**
 306  * Returns array of settings matching input parameters.
 307  *
 308  * @param array $params
 309  *   Array of one or more valid property_name=>value pairs.
 310  *
 311  * @return array
 312  *   Array of matching settings
 313  */
 314 function civicrm_api3_setting_get($params) {
 315   $domains = _civicrm_api3_setting_getDomainArray($params);
 316   $result = CRM_Core_BAO_Setting::getItems($params, $domains, CRM_Utils_Array::value('return', $params, array()));
 317   return civicrm_api3_create_success($result, $params, 'Setting', 'get');
 318 }
 319 /**
 320  * Metadata for setting create function.
 321  *
 322  * @param array $params
 323  *   Parameters as passed to the API.
 324  */
 325 function _civicrm_api3_setting_get_spec(&$params) {
 326   $params['domain_id'] = array(
 327     'api.default' => 'current_domain',
 328     'title' => 'Setting Domain',
 329     'description' => 'if you do not pass in a domain id this will default to the current domain',
 330   );
 331   $params['group'] = array(
 332     'title' => 'Setting Group',
 333     'description' => 'if you know the group defining it will make the api more efficient',
 334   );
 335 }
 336 /**
 337  * Returns value for specific parameter.
 338  *
 339  * Function requires more fields than 'get' but is intended for
 340  * runtime usage & should be quicker
 341  *
 342  * @param array $params
 343  *   Array of one or more valid.
 344  *                       property_name=>value pairs.
 345  *
 346  * @return array
 347  *   API result array.
 348  */
 349 function civicrm_api3_setting_getvalue($params) {
 350   //$config = CRM_Core_Config::singleton();
 351   //if (isset($config->$params['name'])) {
 352   //  return $config->$params['name'];
 353   //}
 354   return CRM_Core_BAO_Setting::getItem(
 355     NULL,
 356     CRM_Utils_Array::value('name', $params),
 357     CRM_Utils_Array::value('component_id', $params),
 358     CRM_Utils_Array::value('default_value', $params),
 359     CRM_Utils_Array::value('contact_id', $params),
 360     CRM_Utils_Array::value('domain_id', $params)
 361   );
 362 }
 363
 364 /**
 365  * Metadata for setting create function.
 366  *
 367  * @param array $params
 368  *   Parameters as passed to the API.
 369  */
 370 function _civicrm_api3_setting_getvalue_spec(&$params) {
 371
 372   $params['group'] = array(
 373     'title' => 'Settings Group',
 374     'api.required' => TRUE,
 375   );
 376   $params['name'] = array(
 377     'title' => 'Setting Name',
 378     'api.aliases' => array('return'),
 379   );
 380   $params['default_value'] = array(
 381     'title' => 'Default Value',
 382   );
 383   $params['component_id'] = array(
 384     'title' => 'Component Id',
 385   );
 386   $params['contact_id'] = array(
 387     'title' => 'Contact Id',
 388   );
 389   $params['domain_id'] = array(
 390     'title' => 'Setting Domain',
 391     'description' => 'if you do not pass in a domain id this will default to the current domain',
 392   );
 393 }
 394
 395 /**
 396  * Converts domain input into an array.
 397  *
 398  * If an array is passed in this is used, if 'all' is passed
 399  * in this is converted to 'all arrays'
 400  *
 401  * Really domain_id should always be set but doing an empty check because at the moment
 402  * using crm-editable will pass an id & default won't be applied
 403  * we did talk about id being a pseudonym for domain_id in this api so applying it here.
 404  *
 405  * @param array $params
 406  *
 407  * @return array
 408  * @throws \Exception
 409  */
 410 function _civicrm_api3_setting_getDomainArray(&$params) {
 411   if (empty($params['domain_id']) && isset($params['id'])) {
 412     $params['domain_id'] = $params['id'];
 413   }
 414
 415   if ($params['domain_id'] == 'current_domain') {
 416     $params['domain_id']    = CRM_Core_Config::domainID();
 417   }
 418
 419   if ($params['domain_id'] == 'all') {
 420     $domainAPIResult = civicrm_api('domain', 'get', array('version' => 3, 'return' => 'id'));
 421     if (isset($domainAPIResult['values'])) {
 422       $params['domain_id'] = array_keys($domainAPIResult['values']);
 423     }
 424     else {
 425       throw new Exception('All domains not retrieved - problem with Domain Get api call ' . $domainAPIResult['error_message']);
 426     }
 427   }
 428   if (is_array($params['domain_id'])) {
 429     $domains = $params['domain_id'];
 430   }
 431   else {
 432     $domains = array($params['domain_id']);
 433   }
 434   return $domains;
 435 }