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