api/v3/Setting.php

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