api/v3/Setting.php

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