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