crm.fsf.org/20131203/files/sites/all/modules-new/civicrm/api/v3/Setting.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.6                                                |
   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  * Revert settings to defaults.
 149  *
 150  * @param array $params
 151  *
 152  * @return array
 153  * @throws \Exception
 154  */
 155 function civicrm_api3_setting_revert(&$params) {
 156   $defaults = civicrm_api('Setting', 'getdefaults', $params);
 157   $fields = civicrm_api('Setting', 'getfields', $params);
 158   $fields = $fields['values'];
 159   $domains = _civicrm_api3_setting_getDomainArray($params);
 160   $result = array();
 161   foreach ($domains as $domainID) {
 162     $valuesToRevert = array_intersect_key($defaults['values'][$domainID], $fields);
 163     if (!empty($valuesToRevert)) {
 164       $valuesToRevert['version'] = $params['version'];
 165       $valuesToRevert['domain_id'] = $domainID;
 166       // note that I haven't looked at how the result would appear with multiple domains in play
 167       $result = array_merge($result, civicrm_api('Setting', 'create', $valuesToRevert));
 168     }
 169   }
 170
 171   return civicrm_api3_create_success($result, $params, 'Setting', 'revert');
 172 }
 173
 174 /**
 175  * Alter metadata for getfields functions.
 176  *
 177  * @param array $params
 178  */
 179 function _civicrm_api3_setting_revert_spec(&$params) {
 180   $params['name'] = array(
 181     'title' => 'Name',
 182     'description' => 'Setting Name belongs to',
 183   );
 184   $params['component_id'] = array(
 185     'title' => 'Component ID',
 186     'description' => 'ID of relevant component',
 187   );
 188   $params['domain_id'] = array(
 189     'api.default' => 'current_domain',
 190     'description' => 'Defaults may differ by domain - if you do not pass in a domain id this will default to the current domain'
 191     . ' an array or "all" are acceptable values for multiple domains',
 192     'title' => 'Setting Domain',
 193   );
 194 }
 195
 196 /**
 197  * Revert settings to defaults.
 198  *
 199  * @param array $params
 200  *
 201  * @return array
 202  * @throws \CiviCRM_API3_Exception
 203  * @throws \Exception
 204  */
 205 function civicrm_api3_setting_fill(&$params) {
 206   $defaults = civicrm_api3('Setting', 'getdefaults', $params);
 207   $domains = _civicrm_api3_setting_getDomainArray($params);
 208   $result = array();
 209   foreach ($domains as $domainID) {
 210     $apiArray = array(
 211       'version' => $params['version'],
 212       'domain_id' => $domainID,
 213     );
 214     $existing = civicrm_api3('Setting', 'get', $apiArray);
 215     $valuesToFill = array_diff_key($defaults['values'][$domainID], $existing['values'][$domainID]);
 216     if (!empty($valuesToFill)) {
 217       $result = array_merge($result, civicrm_api('Setting', 'create', $valuesToFill + $apiArray));
 218     }
 219   }
 220   return civicrm_api3_create_success($result, $params, 'Setting', 'fill');
 221 }
 222
 223 /**
 224  * Alter metadata for getfields functions.
 225  *
 226  * @param array $params
 227  */
 228 function _civicrm_api3_setting_fill_spec(&$params) {
 229   $params['name'] = array(
 230     'title' => 'Name',
 231     'description' => 'Setting Name belongs to',
 232   );
 233   $params['component_id'] = array(
 234     'title' => 'Component ID',
 235     'description' => 'ID of relevant component',
 236   );
 237   $params['domain_id'] = array(
 238     'api.default' => 'current_domain',
 239     'title' => 'Setting Domain',
 240     'description' => 'Defaults may differ by domain - if you do not pass in a domain id this will default to the '
 241     . 'current domain, an array or "all" are acceptable values for multiple domains',
 242   );
 243 }
 244
 245 /**
 246  * Create or update a setting.
 247  *
 248  * @param array $params
 249  *   Parameters as per getfields.
 250  *
 251  * @return array
 252  *   api result array
 253  */
 254 function civicrm_api3_setting_create($params) {
 255   $domains = _civicrm_api3_setting_getDomainArray($params);
 256   $result = CRM_Core_BAO_Setting::setItems($params, $domains);
 257   return civicrm_api3_create_success($result, $params, 'Setting', 'create');
 258 }
 259
 260 /**
 261  * Metadata for setting create function.
 262  *
 263  * @param array $params
 264  *   Parameters as passed to the API.
 265  */
 266 function _civicrm_api3_setting_create_spec(&$params) {
 267   $params['domain_id'] = array(
 268     'api.default' => 'current_domain',
 269     'title' => 'Setting Domain',
 270     'description' => 'if you do not pass in a domain id this will default to the current domain
 271       an array or "all" are acceptable values for multiple domains',
 272   );
 273   $params['group'] = array(
 274     'title' => 'Setting Group',
 275     'description' => 'if you know the group defining it will make the api more efficient',
 276   );
 277 }
 278
 279 /**
 280  * Returns array of settings matching input parameters.
 281  *
 282  * @param array $params
 283  *   Array of one or more valid property_name=>value pairs.
 284  *
 285  * @return array
 286  *   Array of matching settings
 287  */
 288 function civicrm_api3_setting_get($params) {
 289   $domains = _civicrm_api3_setting_getDomainArray($params);
 290   $result = $result = CRM_Core_BAO_Setting::getItems($params, $domains, CRM_Utils_Array::value('return', $params, array()));
 291   return civicrm_api3_create_success($result, $params, 'Setting', 'get');
 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_get_spec(&$params) {
 300   $params['domain_id'] = array(
 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   );
 305   $params['group'] = array(
 306     'title' => 'Setting Group',
 307     'description' => 'if you know the group defining it will make the api more efficient',
 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     $params['group'],
 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'] = array(
 347     'title' => 'Settings Group',
 348     'api.required' => TRUE,
 349   );
 350   $params['name'] = array(
 351     'title' => 'Setting Name',
 352     'api.aliases' => array('return'),
 353   );
 354   $params['default_value'] = array(
 355     'title' => 'Default Value',
 356   );
 357   $params['component_id'] = array(
 358     'title' => 'Component Id',
 359   );
 360   $params['contact_id'] = array(
 361     'title' => 'Contact Id',
 362   );
 363   $params['domain_id'] = array(
 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', array('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 = array($params['domain_id']);
 407   }
 408   return $domains;
 409 }