Commit | Line | Data |
---|---|---|
6a488035 TO |
1 | <?php |
2 | /* | |
3 | +--------------------------------------------------------------------+ | |
fee14197 | 4 | | CiviCRM version 5 | |
6a488035 | 5 | +--------------------------------------------------------------------+ |
6b83d5bd | 6 | | Copyright CiviCRM LLC (c) 2004-2019 | |
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 | /** | |
c28e1768 | 29 | * This api exposes CiviCRM configuration settings. |
6a488035 | 30 | * |
b081365f | 31 | * @package CiviCRM_APIv3 |
61fe4988 EM |
32 | */ |
33 | ||
34 | /** | |
35 | * Get fields for setting api calls. | |
36 | * | |
d0997921 | 37 | * @param array $params |
61fe4988 | 38 | * |
645ee340 | 39 | * @return array |
6a488035 | 40 | */ |
6a488035 | 41 | function civicrm_api3_setting_getfields($params) { |
9b873358 | 42 | if (!empty($params['action']) && strtolower($params['action']) == 'getvalue') { |
6a488035 TO |
43 | $result = array( |
44 | 'name' => array( | |
45 | 'title' => 'name of setting field', | |
46 | 'api.required' => 1, | |
47 | 'type' => CRM_Utils_Type::T_STRING), | |
c14d6dd1 | 48 | 'group' => array( |
6a488035 | 49 | 'api.required' => 0, |
1fdb479f | 50 | 'title' => 'Setting Group', |
6a488035 | 51 | 'description' => 'Settings Group. This is required if the setting is not stored in config', |
21dfd5f5 | 52 | 'type' => CRM_Utils_Type::T_STRING), |
e7483cbe | 53 | ); |
244bbdd8 | 54 | return civicrm_api3_create_success($result, $params, 'Setting', 'getfields'); |
6a488035 | 55 | } |
9b873358 | 56 | if (!empty($params['name'])) { |
6a488035 TO |
57 | //am of two minds about special handling for 'name' as opposed to other filters - but is does make most common |
58 | //usage really easy | |
59 | $params['filters']['name'] = $params['name']; | |
60 | } | |
61 | $result = CRM_Core_BAO_Setting::getSettingSpecification( | |
35671d00 | 62 | CRM_Utils_Array::value('component_id', $params), |
6a488035 | 63 | CRM_Utils_Array::value('filters', $params, array()), |
35671d00 TO |
64 | CRM_Utils_Array::value('domain_id', $params, NULL), |
65 | CRM_Utils_Array::value('profile', $params, NULL) | |
6a488035 TO |
66 | ); |
67 | // find any supplemental information | |
9b873358 | 68 | if (!empty($params['action'])) { |
f60289e9 | 69 | $specFunction = '_civicrm_api3_setting_' . strtolower($params['action']) . '_spec'; |
6a488035 TO |
70 | if (function_exists($specFunction)) { |
71 | $specFunction($result); | |
72 | } | |
73 | } | |
244bbdd8 | 74 | return civicrm_api3_create_success($result, $params, 'Setting', 'getfields'); |
6a488035 | 75 | } |
11e09c59 TO |
76 | |
77 | /** | |
1747ab99 EM |
78 | * Alter metadata for getfields functions. |
79 | * | |
d0997921 | 80 | * @param array $params |
6a488035 | 81 | */ |
f60289e9 | 82 | function _civicrm_api3_setting_getfields_spec(&$params) { |
b2ed8e73 CW |
83 | $params['filters'] = array( |
84 | 'title' => 'Filters', | |
85 | 'description' => 'Fields you wish to filter by e.g. array("group_name" => "CiviCRM Preferences")', | |
86 | ); | |
87 | $params['component_id'] = array( | |
88 | 'title' => 'Component ID', | |
89 | 'description' => 'ID of relevant component', | |
90 | ); | |
91 | $params['profile'] = array( | |
92 | 'title' => 'Profile', | |
93 | 'description' => 'Profile is passed through to hooks & added to cachestring', | |
94 | ); | |
6a488035 | 95 | } |
11e09c59 TO |
96 | |
97 | /** | |
1747ab99 EM |
98 | * Return default values for settings. |
99 | * | |
100 | * We will domain key this as it could vary by domain (ie. urls) | |
6a488035 | 101 | * as we will be creating the option for a function rather than an value to be in the defaults |
1747ab99 EM |
102 | * Note that is not in place as yet. |
103 | * | |
d0997921 | 104 | * @param array $params |
1747ab99 | 105 | * |
645ee340 EM |
106 | * @return array |
107 | * @throws \CiviCRM_API3_Exception | |
108 | * @throws \Exception | |
6a488035 | 109 | */ |
9b873358 | 110 | function civicrm_api3_setting_getdefaults(&$params) { |
244bbdd8 | 111 | $settings = civicrm_api3('Setting', 'getfields', $params); |
6a488035 TO |
112 | $domains = _civicrm_api3_setting_getDomainArray($params); |
113 | $defaults = array(); | |
9b873358 | 114 | foreach ($domains as $domainID) { |
6a488035 | 115 | $defaults[$domainID] = array(); |
9b873358 TO |
116 | foreach ($settings['values'] as $setting => $spec) { |
117 | if (array_key_exists('default', $spec) && !is_null($spec['default'])) { | |
6a488035 TO |
118 | $defaults[$domainID][$setting] = $spec['default']; |
119 | } | |
6a488035 TO |
120 | } |
121 | } | |
244bbdd8 | 122 | return civicrm_api3_create_success($defaults, $params, 'Setting', 'getfields'); |
6a488035 | 123 | } |
11e09c59 | 124 | /** |
244bbdd8 | 125 | * Metadata for Setting create function. |
11e09c59 | 126 | * |
cf470720 TO |
127 | * @param array $params |
128 | * Parameters as passed to the API. | |
11e09c59 | 129 | */ |
f60289e9 | 130 | function _civicrm_api3_setting_getdefaults_spec(&$params) { |
6a488035 | 131 | $params['domain_id'] = array( |
5a159702 EM |
132 | 'api.default' => 'current_domain', |
133 | 'description' => 'Defaults may differ by domain - if you do not pass in a domain id this will default to the current domain | |
134 | an array or "all" are acceptable values for multiple domains', | |
135 | 'title' => 'Setting Domain', | |
6a488035 TO |
136 | ); |
137 | } | |
11e09c59 | 138 | |
70599df6 | 139 | /** |
140 | * Get options for settings. | |
141 | * | |
142 | * @param array $params | |
143 | * | |
144 | * @return array | |
145 | * @throws \API_Exception | |
146 | */ | |
76068c6a TO |
147 | function civicrm_api3_setting_getoptions($params) { |
148 | $specs = CRM_Core_BAO_Setting::getSettingSpecification(); | |
149 | ||
150 | if (empty($specs[$params['field']]) || empty($specs[$params['field']]['pseudoconstant'])) { | |
151 | throw new API_Exception("The field '" . $params['field'] . "' has no associated option list."); | |
152 | } | |
153 | ||
154 | $pseudoconstant = $specs[$params['field']]['pseudoconstant']; | |
155 | ||
156 | // It would be nice if we could leverage CRM_Core_PseudoConstant::get() somehow, | |
157 | // but it's tightly coupled to DAO/field. However, if you really need to support | |
158 | // more pseudoconstant types, then probably best to refactor it. For now, KISS. | |
159 | if (!empty($pseudoconstant['callback'])) { | |
160 | $values = Civi\Core\Resolver::singleton()->call($pseudoconstant['callback'], array()); | |
161 | return civicrm_api3_create_success($values, $params, 'Setting', 'getoptions'); | |
162 | } | |
03c5ceba | 163 | elseif (!empty($pseudoconstant['optionGroupName'])) { |
babfca87 SL |
164 | $keyColumn = 'value'; |
165 | if (!empty($pseudoconstant['keyColumn'])) { | |
166 | $keyColumn = $pseudoconstant['keyColumn']; | |
167 | } | |
03c5ceba | 168 | return civicrm_api3_create_success( |
babfca87 | 169 | CRM_Core_OptionGroup::values($pseudoconstant['optionGroupName'], FALSE, FALSE, TRUE, NULL, 'label', TRUE, FALSE, $keyColumn), |
03c5ceba | 170 | $params, 'Setting', 'getoptions' |
171 | ); | |
172 | } | |
76068c6a TO |
173 | |
174 | throw new API_Exception("The field '" . $params['field'] . "' uses an unsupported option list."); | |
175 | } | |
176 | ||
11e09c59 | 177 | /** |
9d32e6f7 EM |
178 | * Revert settings to defaults. |
179 | * | |
d0997921 | 180 | * @param array $params |
9d32e6f7 | 181 | * |
645ee340 EM |
182 | * @return array |
183 | * @throws \Exception | |
6a488035 | 184 | */ |
9b873358 | 185 | function civicrm_api3_setting_revert(&$params) { |
244bbdd8 CW |
186 | $defaults = civicrm_api('Setting', 'getdefaults', $params); |
187 | $fields = civicrm_api('Setting', 'getfields', $params); | |
6a488035 TO |
188 | $fields = $fields['values']; |
189 | $domains = _civicrm_api3_setting_getDomainArray($params); | |
190 | $result = array(); | |
9b873358 | 191 | foreach ($domains as $domainID) { |
6a488035 | 192 | $valuesToRevert = array_intersect_key($defaults['values'][$domainID], $fields); |
9b873358 | 193 | if (!empty($valuesToRevert)) { |
6a488035 TO |
194 | $valuesToRevert['version'] = $params['version']; |
195 | $valuesToRevert['domain_id'] = $domainID; | |
196 | // note that I haven't looked at how the result would appear with multiple domains in play | |
244bbdd8 | 197 | $result = array_merge($result, civicrm_api('Setting', 'create', $valuesToRevert)); |
6a488035 TO |
198 | } |
199 | } | |
200 | ||
244bbdd8 | 201 | return civicrm_api3_create_success($result, $params, 'Setting', 'revert'); |
6a488035 | 202 | } |
11e09c59 TO |
203 | |
204 | /** | |
dc64d047 EM |
205 | * Alter metadata for getfields functions. |
206 | * | |
d0997921 | 207 | * @param array $params |
11e09c59 | 208 | */ |
f60289e9 | 209 | function _civicrm_api3_setting_revert_spec(&$params) { |
b2ed8e73 CW |
210 | $params['name'] = array( |
211 | 'title' => 'Name', | |
212 | 'description' => 'Setting Name belongs to', | |
213 | ); | |
214 | $params['component_id'] = array( | |
215 | 'title' => 'Component ID', | |
216 | 'description' => 'ID of relevant component', | |
217 | ); | |
6a488035 TO |
218 | $params['domain_id'] = array( |
219 | 'api.default' => 'current_domain', | |
dc64d047 EM |
220 | 'description' => 'Defaults may differ by domain - if you do not pass in a domain id this will default to the current domain' |
221 | . ' an array or "all" are acceptable values for multiple domains', | |
5a159702 | 222 | 'title' => 'Setting Domain', |
6a488035 TO |
223 | ); |
224 | } | |
225 | ||
11e09c59 | 226 | /** |
1747ab99 EM |
227 | * Revert settings to defaults. |
228 | * | |
d0997921 | 229 | * @param array $params |
1747ab99 | 230 | * |
645ee340 EM |
231 | * @return array |
232 | * @throws \CiviCRM_API3_Exception | |
233 | * @throws \Exception | |
11e09c59 | 234 | */ |
9b873358 | 235 | function civicrm_api3_setting_fill(&$params) { |
244bbdd8 | 236 | $defaults = civicrm_api3('Setting', 'getdefaults', $params); |
6a488035 TO |
237 | $domains = _civicrm_api3_setting_getDomainArray($params); |
238 | $result = array(); | |
9b873358 | 239 | foreach ($domains as $domainID) { |
6a488035 TO |
240 | $apiArray = array( |
241 | 'version' => $params['version'], | |
21dfd5f5 | 242 | 'domain_id' => $domainID, |
6a488035 | 243 | ); |
244bbdd8 | 244 | $existing = civicrm_api3('Setting', 'get', $apiArray); |
6a488035 | 245 | $valuesToFill = array_diff_key($defaults['values'][$domainID], $existing['values'][$domainID]); |
9b873358 | 246 | if (!empty($valuesToFill)) { |
244bbdd8 | 247 | $result = array_merge($result, civicrm_api('Setting', 'create', $valuesToFill + $apiArray)); |
6a488035 TO |
248 | } |
249 | } | |
244bbdd8 | 250 | return civicrm_api3_create_success($result, $params, 'Setting', 'fill'); |
6a488035 | 251 | } |
11e09c59 TO |
252 | |
253 | /** | |
9d32e6f7 EM |
254 | * Alter metadata for getfields functions. |
255 | * | |
d0997921 | 256 | * @param array $params |
11e09c59 | 257 | */ |
f60289e9 | 258 | function _civicrm_api3_setting_fill_spec(&$params) { |
b2ed8e73 CW |
259 | $params['name'] = array( |
260 | 'title' => 'Name', | |
261 | 'description' => 'Setting Name belongs to', | |
262 | ); | |
263 | $params['component_id'] = array( | |
264 | 'title' => 'Component ID', | |
265 | 'description' => 'ID of relevant component', | |
266 | ); | |
6a488035 | 267 | $params['domain_id'] = array( |
5a159702 EM |
268 | 'api.default' => 'current_domain', |
269 | 'title' => 'Setting Domain', | |
1747ab99 | 270 | 'description' => 'Defaults may differ by domain - if you do not pass in a domain id this will default to the ' |
dc64d047 | 271 | . 'current domain, an array or "all" are acceptable values for multiple domains', |
6a488035 TO |
272 | ); |
273 | } | |
274 | ||
275 | /** | |
35823763 | 276 | * Create or update a setting. |
6a488035 | 277 | * |
cf470720 | 278 | * @param array $params |
35823763 | 279 | * Parameters as per getfields. |
6a488035 | 280 | * |
a6c01b45 | 281 | * @return array |
72b3a70c | 282 | * api result array |
6a488035 TO |
283 | */ |
284 | function civicrm_api3_setting_create($params) { | |
285 | $domains = _civicrm_api3_setting_getDomainArray($params); | |
286 | $result = CRM_Core_BAO_Setting::setItems($params, $domains); | |
244bbdd8 | 287 | return civicrm_api3_create_success($result, $params, 'Setting', 'create'); |
6a488035 | 288 | } |
11e09c59 TO |
289 | |
290 | /** | |
1747ab99 | 291 | * Metadata for setting create function. |
6a488035 | 292 | * |
cf470720 TO |
293 | * @param array $params |
294 | * Parameters as passed to the API. | |
6a488035 | 295 | */ |
f60289e9 | 296 | function _civicrm_api3_setting_create_spec(&$params) { |
6a488035 TO |
297 | $params['domain_id'] = array( |
298 | 'api.default' => 'current_domain', | |
5a159702 | 299 | 'title' => 'Setting Domain', |
6a488035 | 300 | 'description' => 'if you do not pass in a domain id this will default to the current domain |
21dfd5f5 | 301 | an array or "all" are acceptable values for multiple domains', |
e7483cbe | 302 | ); |
35671d00 | 303 | $params['group'] = array( |
e7483cbe J |
304 | 'title' => 'Setting Group', |
305 | 'description' => 'if you know the group defining it will make the api more efficient', | |
306 | ); | |
6a488035 TO |
307 | } |
308 | ||
309 | /** | |
35823763 | 310 | * Returns array of settings matching input parameters. |
6a488035 | 311 | * |
cf470720 | 312 | * @param array $params |
35823763 | 313 | * Array of one or more valid property_name=>value pairs. |
6a488035 | 314 | * |
a6c01b45 | 315 | * @return array |
72b3a70c | 316 | * Array of matching settings |
6a488035 TO |
317 | */ |
318 | function civicrm_api3_setting_get($params) { | |
319 | $domains = _civicrm_api3_setting_getDomainArray($params); | |
299cd62a | 320 | $result = CRM_Core_BAO_Setting::getItems($params, $domains, CRM_Utils_Array::value('return', $params, array())); |
244bbdd8 | 321 | return civicrm_api3_create_success($result, $params, 'Setting', 'get'); |
6a488035 | 322 | } |
11e09c59 | 323 | /** |
1747ab99 | 324 | * Metadata for setting create function. |
11e09c59 | 325 | * |
cf470720 TO |
326 | * @param array $params |
327 | * Parameters as passed to the API. | |
11e09c59 | 328 | */ |
f60289e9 | 329 | function _civicrm_api3_setting_get_spec(&$params) { |
6a488035 | 330 | $params['domain_id'] = array( |
5a159702 EM |
331 | 'api.default' => 'current_domain', |
332 | 'title' => 'Setting Domain', | |
21dfd5f5 | 333 | 'description' => 'if you do not pass in a domain id this will default to the current domain', |
6a488035 TO |
334 | ); |
335 | $params['group'] = array( | |
5a159702 | 336 | 'title' => 'Setting Group', |
21dfd5f5 | 337 | 'description' => 'if you know the group defining it will make the api more efficient', |
35671d00 | 338 | ); |
6a488035 TO |
339 | } |
340 | /** | |
1747ab99 EM |
341 | * Returns value for specific parameter. |
342 | * | |
343 | * Function requires more fields than 'get' but is intended for | |
6a488035 TO |
344 | * runtime usage & should be quicker |
345 | * | |
cf470720 | 346 | * @param array $params |
1747ab99 | 347 | * Array of one or more valid. |
6a488035 TO |
348 | * property_name=>value pairs. |
349 | * | |
a6c01b45 | 350 | * @return array |
1747ab99 | 351 | * API result array. |
6a488035 TO |
352 | */ |
353 | function civicrm_api3_setting_getvalue($params) { | |
86bfd7a8 TO |
354 | //$config = CRM_Core_Config::singleton(); |
355 | //if (isset($config->$params['name'])) { | |
356 | // return $config->$params['name']; | |
357 | //} | |
6a488035 | 358 | return CRM_Core_BAO_Setting::getItem( |
5cb4bffc | 359 | NULL, |
6a488035 TO |
360 | CRM_Utils_Array::value('name', $params), |
361 | CRM_Utils_Array::value('component_id', $params), | |
362 | CRM_Utils_Array::value('default_value', $params), | |
363 | CRM_Utils_Array::value('contact_id', $params), | |
364 | CRM_Utils_Array::value('domain_id', $params) | |
365 | ); | |
366 | } | |
367 | ||
11e09c59 | 368 | /** |
1747ab99 | 369 | * Metadata for setting create function. |
11e09c59 | 370 | * |
cf470720 TO |
371 | * @param array $params |
372 | * Parameters as passed to the API. | |
11e09c59 | 373 | */ |
f60289e9 | 374 | function _civicrm_api3_setting_getvalue_spec(&$params) { |
6a488035 TO |
375 | |
376 | $params['group'] = array( | |
e7483cbe J |
377 | 'title' => 'Settings Group', |
378 | 'api.required' => TRUE, | |
6a488035 TO |
379 | ); |
380 | $params['name'] = array( | |
e7483cbe J |
381 | 'title' => 'Setting Name', |
382 | 'api.aliases' => array('return'), | |
6a488035 TO |
383 | ); |
384 | $params['default_value'] = array( | |
e7483cbe | 385 | 'title' => 'Default Value', |
6a488035 TO |
386 | ); |
387 | $params['component_id'] = array( | |
e7483cbe | 388 | 'title' => 'Component Id', |
6a488035 TO |
389 | ); |
390 | $params['contact_id'] = array( | |
e7483cbe | 391 | 'title' => 'Contact Id', |
6a488035 TO |
392 | ); |
393 | $params['domain_id'] = array( | |
5a159702 | 394 | 'title' => 'Setting Domain', |
21dfd5f5 | 395 | 'description' => 'if you do not pass in a domain id this will default to the current domain', |
6a488035 TO |
396 | ); |
397 | } | |
11e09c59 TO |
398 | |
399 | /** | |
1747ab99 EM |
400 | * Converts domain input into an array. |
401 | * | |
402 | * If an array is passed in this is used, if 'all' is passed | |
6a488035 | 403 | * in this is converted to 'all arrays' |
f60289e9 | 404 | * |
405 | * Really domain_id should always be set but doing an empty check because at the moment | |
406 | * using crm-editable will pass an id & default won't be applied | |
1747ab99 EM |
407 | * we did talk about id being a pseudonym for domain_id in this api so applying it here. |
408 | * | |
d0997921 | 409 | * @param array $params |
1747ab99 | 410 | * |
645ee340 EM |
411 | * @return array |
412 | * @throws \Exception | |
6a488035 | 413 | */ |
9b873358 TO |
414 | function _civicrm_api3_setting_getDomainArray(&$params) { |
415 | if (empty($params['domain_id']) && isset($params['id'])) { | |
f60289e9 | 416 | $params['domain_id'] = $params['id']; |
417 | } | |
418 | ||
9b873358 | 419 | if ($params['domain_id'] == 'current_domain') { |
6a488035 TO |
420 | $params['domain_id'] = CRM_Core_Config::domainID(); |
421 | } | |
422 | ||
9b873358 | 423 | if ($params['domain_id'] == 'all') { |
35671d00 | 424 | $domainAPIResult = civicrm_api('domain', 'get', array('version' => 3, 'return' => 'id')); |
6a488035 TO |
425 | if (isset($domainAPIResult['values'])) { |
426 | $params['domain_id'] = array_keys($domainAPIResult['values']); | |
427 | } | |
92e4c2a5 | 428 | else { |
6a488035 TO |
429 | throw new Exception('All domains not retrieved - problem with Domain Get api call ' . $domainAPIResult['error_message']); |
430 | } | |
431 | } | |
9b873358 | 432 | if (is_array($params['domain_id'])) { |
6a488035 TO |
433 | $domains = $params['domain_id']; |
434 | } | |
92e4c2a5 | 435 | else { |
6a488035 TO |
436 | $domains = array($params['domain_id']); |
437 | } | |
438 | return $domains; | |
439 | } |