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