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