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