api/v3/Setting.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.6                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2014                                |
   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('title' => 'Fields you wish to filter by e.g. array("group_name" => "CiviCRM Preferences")');
  84   $params['component_id'] = array('title' => 'id of relevant component');
  85   $params['profile'] = array('title' => 'profile is passed through to hooks & added to cachestring');
  86 }
  87
  88 /**
  89  * Return default values for settings.
  90  *
  91  * We will domain key this as it could vary by domain (ie. urls)
  92  * as we will be creating the option for a function rather than an value to be in the defaults
  93  * Note that is not in place as yet.
  94  *
  95  * @param array $params
  96  *
  97  * @return array
  98  * @throws \CiviCRM_API3_Exception
  99  * @throws \Exception
 100  */
 101 function civicrm_api3_setting_getdefaults(&$params) {
 102   $settings = civicrm_api3('setting', 'getfields', $params);
 103   $domains = _civicrm_api3_setting_getDomainArray($params);
 104   $defaults = array();
 105   foreach ($domains as $domainID) {
 106     $defaults[$domainID] = array();
 107     $noDefaults = array();
 108     foreach ($settings['values'] as $setting => $spec) {
 109       if (array_key_exists('default', $spec) && !is_null($spec['default'])) {
 110         $defaults[$domainID][$setting] = $spec['default'];
 111       }
 112       else {
 113         $noDefaults[$setting] = 1;
 114       }
 115     }
 116     if (!empty($params['debug'])) {
 117       // we are only tracking 'noDefaults' to help us check the xml
 118       print_r($noDefaults);
 119     }
 120   }
 121   return civicrm_api3_create_success($defaults, $params, 'setting', 'getfields');
 122 }
 123 /**
 124  * Metadata for setting create function.
 125  *
 126  * @param array $params
 127  *   Parameters as passed to the API.
 128  */
 129 function _civicrm_api3_setting_getdefaults_spec(&$params) {
 130   $params['domain_id'] = array(
 131     'api.default' => 'current_domain',
 132     'description' => 'Defaults may differ by domain - if you do not pass in a domain id this will default to the current domain
 133       an array or "all" are acceptable values for multiple domains',
 134     'title' => 'Setting Domain',
 135   );
 136 }
 137
 138 /**
 139  * Revert settings to defaults.
 140  *
 141  * @param array $params
 142  *
 143  * @return array
 144  * @throws \Exception
 145  */
 146 function civicrm_api3_setting_revert(&$params) {
 147   $defaults = civicrm_api('setting', 'getdefaults', $params);
 148   $fields = civicrm_api('setting', 'getfields', $params);
 149   $fields = $fields['values'];
 150   $domains = _civicrm_api3_setting_getDomainArray($params);
 151   $result = array();
 152   foreach ($domains as $domainID) {
 153     $valuesToRevert = array_intersect_key($defaults['values'][$domainID], $fields);
 154     if (!empty($valuesToRevert)) {
 155       $valuesToRevert['version'] = $params['version'];
 156       $valuesToRevert['domain_id'] = $domainID;
 157       // note that I haven't looked at how the result would appear with multiple domains in play
 158       $result = array_merge($result, civicrm_api('setting', 'create', $valuesToRevert));
 159     }
 160   }
 161
 162   return civicrm_api3_create_success($result, $params, 'setting', 'revert');
 163 }
 164
 165 /**
 166  * Alter metadata for getfields functions.
 167  *
 168  * @param array $params
 169  */
 170 function _civicrm_api3_setting_revert_spec(&$params) {
 171   $params['name'] = array('title' => 'Setting Name belongs to');
 172   $params['component_id'] = array('title' => 'id of relevant component');
 173   $params['domain_id'] = array(
 174     'api.default' => 'current_domain',
 175     'description' => 'Defaults may differ by domain - if you do not pass in a domain id this will default to the current domain'
 176     . ' an array or "all" are acceptable values for multiple domains',
 177     'title' => 'Setting Domain',
 178   );
 179 }
 180
 181 /**
 182  * Revert settings to defaults.
 183  *
 184  * @param array $params
 185  *
 186  * @return array
 187  * @throws \CiviCRM_API3_Exception
 188  * @throws \Exception
 189  */
 190 function civicrm_api3_setting_fill(&$params) {
 191   $defaults = civicrm_api3('setting', 'getdefaults', $params);
 192   $domains = _civicrm_api3_setting_getDomainArray($params);
 193   $result = array();
 194   foreach ($domains as $domainID) {
 195     $apiArray = array(
 196       'version' => $params['version'],
 197       'domain_id' => $domainID,
 198     );
 199     $existing = civicrm_api3('setting', 'get', $apiArray);
 200     $valuesToFill = array_diff_key($defaults['values'][$domainID], $existing['values'][$domainID]);
 201     if (!empty($valuesToFill)) {
 202       $result = array_merge($result, civicrm_api('setting', 'create', $valuesToFill + $apiArray));
 203     }
 204   }
 205   return civicrm_api3_create_success($result, $params, 'setting', 'fill');
 206 }
 207
 208 /**
 209  * Alter metadata for getfields functions.
 210  *
 211  * @param array $params
 212  */
 213 function _civicrm_api3_setting_fill_spec(&$params) {
 214   $params['name'] = array('title' => 'Setting Name belongs to');
 215   $params['component_id'] = array('title' => 'id of relevant component');
 216   $params['domain_id'] = array(
 217     'api.default' => 'current_domain',
 218     'title' => 'Setting Domain',
 219     'description' => 'Defaults may differ by domain - if you do not pass in a domain id this will default to the '
 220     . 'current domain, an array or "all" are acceptable values for multiple domains',
 221   );
 222 }
 223
 224 /**
 225  * Create or update a setting.
 226  *
 227  * @param array $params
 228  *   Parameters as per getfields.
 229  *
 230  * @return array
 231  *   api result array
 232  */
 233 function civicrm_api3_setting_create($params) {
 234   $domains = _civicrm_api3_setting_getDomainArray($params);
 235   $result = CRM_Core_BAO_Setting::setItems($params, $domains);
 236   return civicrm_api3_create_success($result, $params, 'setting', 'create');
 237 }
 238
 239 /**
 240  * Metadata for setting create function.
 241  *
 242  * @param array $params
 243  *   Parameters as passed to the API.
 244  */
 245 function _civicrm_api3_setting_create_spec(&$params) {
 246   $params['domain_id'] = array(
 247     'api.default' => 'current_domain',
 248     'title' => 'Setting Domain',
 249     'description' => 'if you do not pass in a domain id this will default to the current domain
 250       an array or "all" are acceptable values for multiple domains',
 251   );
 252   $params['group'] = array(
 253     'title' => 'Setting Group',
 254     'description' => 'if you know the group defining it will make the api more efficient',
 255   );
 256 }
 257
 258 /**
 259  * Returns array of settings matching input parameters.
 260  *
 261  * @param array $params
 262  *   Array of one or more valid property_name=>value pairs.
 263  *
 264  * @return array
 265  *   Array of matching settings
 266  */
 267 function civicrm_api3_setting_get($params) {
 268   $domains = _civicrm_api3_setting_getDomainArray($params);
 269   $result = $result = CRM_Core_BAO_Setting::getItems($params, $domains, CRM_Utils_Array::value('return', $params, array()));
 270   return civicrm_api3_create_success($result, $params, 'setting', 'get');
 271 }
 272 /**
 273  * Metadata for setting create function.
 274  *
 275  * @param array $params
 276  *   Parameters as passed to the API.
 277  */
 278 function _civicrm_api3_setting_get_spec(&$params) {
 279   $params['domain_id'] = array(
 280     'api.default' => 'current_domain',
 281     'title' => 'Setting Domain',
 282     'description' => 'if you do not pass in a domain id this will default to the current domain',
 283   );
 284   $params['group'] = array(
 285     'title' => 'Setting Group',
 286     'description' => 'if you know the group defining it will make the api more efficient',
 287   );
 288 }
 289 /**
 290  * Returns value for specific parameter.
 291  *
 292  * Function requires more fields than 'get' but is intended for
 293  * runtime usage & should be quicker
 294  *
 295  * @param array $params
 296  *   Array of one or more valid.
 297  *                       property_name=>value pairs.
 298  *
 299  * @return array
 300  *   API result array.
 301  */
 302 function civicrm_api3_setting_getvalue($params) {
 303   $config = CRM_Core_Config::singleton();
 304   if (isset($config->$params['name'])) {
 305     return $config->$params['name'];
 306   }
 307   return CRM_Core_BAO_Setting::getItem(
 308     $params['group'],
 309     CRM_Utils_Array::value('name', $params),
 310     CRM_Utils_Array::value('component_id', $params),
 311     CRM_Utils_Array::value('default_value', $params),
 312     CRM_Utils_Array::value('contact_id', $params),
 313     CRM_Utils_Array::value('domain_id', $params)
 314   );
 315 }
 316
 317 /**
 318  * Metadata for setting create function.
 319  *
 320  * @param array $params
 321  *   Parameters as passed to the API.
 322  */
 323 function _civicrm_api3_setting_getvalue_spec(&$params) {
 324
 325   $params['group'] = array(
 326     'title' => 'Settings Group',
 327     'api.required' => TRUE,
 328   );
 329   $params['name'] = array(
 330     'title' => 'Setting Name',
 331     'api.aliases' => array('return'),
 332   );
 333   $params['default_value'] = array(
 334     'title' => 'Default Value',
 335   );
 336   $params['component_id'] = array(
 337     'title' => 'Component Id',
 338   );
 339   $params['contact_id'] = array(
 340     'title' => 'Contact Id',
 341   );
 342   $params['domain_id'] = array(
 343     'title' => 'Setting Domain',
 344     'description' => 'if you do not pass in a domain id this will default to the current domain',
 345   );
 346 }
 347
 348 /**
 349  * Converts domain input into an array.
 350  *
 351  * If an array is passed in this is used, if 'all' is passed
 352  * in this is converted to 'all arrays'
 353  *
 354  * Really domain_id should always be set but doing an empty check because at the moment
 355  * using crm-editable will pass an id & default won't be applied
 356  * we did talk about id being a pseudonym for domain_id in this api so applying it here.
 357  *
 358  * @param array $params
 359  *
 360  * @return array
 361  * @throws \Exception
 362  */
 363 function _civicrm_api3_setting_getDomainArray(&$params) {
 364   if (empty($params['domain_id']) && isset($params['id'])) {
 365     $params['domain_id'] = $params['id'];
 366   }
 367
 368   if ($params['domain_id'] == 'current_domain') {
 369     $params['domain_id']    = CRM_Core_Config::domainID();
 370   }
 371
 372   if ($params['domain_id'] == 'all') {
 373     $domainAPIResult = civicrm_api('domain', 'get', array('version' => 3, 'return' => 'id'));
 374     if (isset($domainAPIResult['values'])) {
 375       $params['domain_id'] = array_keys($domainAPIResult['values']);
 376     }
 377     else {
 378       throw new Exception('All domains not retrieved - problem with Domain Get api call ' . $domainAPIResult['error_message']);
 379     }
 380   }
 381   if (is_array($params['domain_id'])) {
 382     $domains = $params['domain_id'];
 383   }
 384   else {
 385     $domains = array($params['domain_id']);
 386   }
 387   return $domains;
 388 }