3 +--------------------------------------------------------------------+
4 | Copyright CiviCRM LLC. All rights reserved. |
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 |
9 +--------------------------------------------------------------------+
13 * This api exposes CiviCRM configuration settings.
15 * @package CiviCRM_APIv3
19 * Get fields for setting api calls.
21 * @param array $params
25 function civicrm_api3_setting_getfields($params) {
26 if (!empty($params['action']) && strtolower($params['action']) == 'getvalue') {
29 'title' => 'name of setting field',
31 'type' => CRM_Utils_Type
::T_STRING
,
35 'title' => 'Setting Group',
36 'description' => 'Settings Group. This is required if the setting is not stored in config',
37 'type' => CRM_Utils_Type
::T_STRING
,
40 return civicrm_api3_create_success($result, $params, 'Setting', 'getfields');
42 if (!empty($params['name'])) {
43 //am of two minds about special handling for 'name' as opposed to other filters - but is does make most common
45 $params['filters']['name'] = $params['name'];
47 $result = CRM_Core_BAO_Setting
::getSettingSpecification(
48 CRM_Utils_Array
::value('component_id', $params),
49 CRM_Utils_Array
::value('filters', $params, []),
50 CRM_Utils_Array
::value('domain_id', $params, NULL),
51 CRM_Utils_Array
::value('profile', $params, NULL)
53 // find any supplemental information
54 if (!empty($params['action'])) {
55 $specFunction = '_civicrm_api3_setting_' . strtolower($params['action']) . '_spec';
56 if (function_exists($specFunction)) {
57 $specFunction($result);
60 return civicrm_api3_create_success($result, $params, 'Setting', 'getfields');
64 * Alter metadata for getfields functions.
66 * @param array $params
68 function _civicrm_api3_setting_getfields_spec(&$params) {
69 $params['filters'] = [
71 'description' => 'Fields you wish to filter by e.g. array("group_name" => "CiviCRM Preferences")',
73 $params['component_id'] = [
74 'title' => 'Component ID',
75 'description' => 'ID of relevant component',
77 $params['profile'] = [
79 'description' => 'Profile is passed through to hooks & added to cachestring',
84 * Return default values for settings.
86 * 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.
90 * @param array $params
93 * @throws \CiviCRM_API3_Exception
96 function civicrm_api3_setting_getdefaults($params) {
97 $settings = civicrm_api3('Setting', 'getfields', $params);
98 $domains = _civicrm_api3_setting_getDomainArray($params);
100 foreach ($domains as $domainID) {
101 $defaults[$domainID] = [];
102 foreach ($settings['values'] as $setting => $spec) {
103 if (array_key_exists('default', $spec) && !is_null($spec['default'])) {
104 $defaults[$domainID][$setting] = $spec['default'];
108 return civicrm_api3_create_success($defaults, $params, 'Setting', 'getfields');
112 * Metadata for Setting create function.
114 * @param array $params
115 * Parameters as passed to the API.
117 function _civicrm_api3_setting_getdefaults_spec(&$params) {
118 $params['domain_id'] = [
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',
127 * Get options for settings.
129 * @param array $params
132 * @throws \API_Exception
134 function civicrm_api3_setting_getoptions($params) {
135 $domainId = $params['domain_id'] ??
NULL;
136 $specs = \Civi\Core\SettingsMetadata
::getMetadata(['name' => $params['field']], $domainId, TRUE);
138 if (!isset($specs[$params['field']]['options']) ||
!is_array($specs[$params['field']]['options'])) {
139 throw new API_Exception("The field '" . $params['field'] . "' has no associated option list.");
142 return civicrm_api3_create_success($specs[$params['field']]['options'], $params, 'Setting', 'getoptions');
146 * Revert settings to defaults.
148 * @param array $params
153 function civicrm_api3_setting_revert($params) {
154 $defaults = civicrm_api('Setting', 'getdefaults', $params);
155 $fields = civicrm_api('Setting', 'getfields', $params);
156 $fields = $fields['values'];
157 $domains = _civicrm_api3_setting_getDomainArray($params);
159 foreach ($domains as $domainID) {
160 $valuesToRevert = array_intersect_key($defaults['values'][$domainID], $fields);
161 if (!empty($valuesToRevert)) {
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
165 $result = array_merge($result, civicrm_api('Setting', 'create', $valuesToRevert));
169 return civicrm_api3_create_success($result, $params, 'Setting', 'revert');
173 * Alter metadata for getfields functions.
175 * @param array $params
177 function _civicrm_api3_setting_revert_spec(&$params) {
180 'description' => 'Setting Name belongs to',
182 $params['component_id'] = [
183 'title' => 'Component ID',
184 'description' => 'ID of relevant component',
186 $params['domain_id'] = [
187 'api.default' => 'current_domain',
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',
190 'title' => 'Setting Domain',
195 * Revert settings to defaults.
197 * @param array $params
200 * @throws \CiviCRM_API3_Exception
203 function civicrm_api3_setting_fill($params) {
204 $defaults = civicrm_api3('Setting', 'getdefaults', $params);
205 $domains = _civicrm_api3_setting_getDomainArray($params);
207 foreach ($domains as $domainID) {
209 'version' => $params['version'],
210 'domain_id' => $domainID,
212 $existing = civicrm_api3('Setting', 'get', $apiArray);
213 $valuesToFill = array_diff_key($defaults['values'][$domainID], $existing['values'][$domainID]);
214 if (!empty($valuesToFill)) {
215 $result = array_merge($result, civicrm_api('Setting', 'create', $valuesToFill +
$apiArray));
218 return civicrm_api3_create_success($result, $params, 'Setting', 'fill');
222 * Alter metadata for getfields functions.
224 * @param array $params
226 function _civicrm_api3_setting_fill_spec(&$params) {
229 'description' => 'Setting Name belongs to',
231 $params['component_id'] = [
232 'title' => 'Component ID',
233 'description' => 'ID of relevant component',
235 $params['domain_id'] = [
236 'api.default' => 'current_domain',
237 'title' => 'Setting Domain',
238 'description' => 'Defaults may differ by domain - if you do not pass in a domain id this will default to the '
239 . 'current domain, an array or "all" are acceptable values for multiple domains',
244 * Declare deprecated api functions.
248 function _civicrm_api3_setting_deprecation() {
249 return ['fill' => 'Setting "fill" is no longer necessary.'];
253 * Create or update a setting.
255 * @param array $params
256 * Parameters as per getfields.
261 * @throws \API_Exception
262 * @throws \CiviCRM_API3_Exception
264 function civicrm_api3_setting_create($params) {
265 $domains = _civicrm_api3_setting_getDomainArray($params);
266 $result = CRM_Core_BAO_Setting
::setItems($params, $domains);
267 return civicrm_api3_create_success($result, $params, 'Setting', 'create');
271 * Metadata for setting create function.
273 * @param array $params
274 * Parameters as passed to the API.
276 function _civicrm_api3_setting_create_spec(&$params) {
277 $params['domain_id'] = [
278 'api.default' => 'current_domain',
279 'title' => 'Setting Domain',
280 'description' => 'if you do not pass in a domain id this will default to the current domain
281 an array or "all" are acceptable values for multiple domains',
284 'title' => 'Setting Group',
285 'description' => 'if you know the group defining it will make the api more efficient',
290 * Returns array of settings matching input parameters.
292 * @param array $params
293 * Array of one or more valid property_name=>value pairs.
296 * Array of matching settings
298 function civicrm_api3_setting_get($params) {
299 $domains = _civicrm_api3_setting_getDomainArray($params);
300 $result = CRM_Core_BAO_Setting
::getItems($params, $domains, CRM_Utils_Array
::value('return', $params, []));
301 return civicrm_api3_create_success($result, $params, 'Setting', 'get');
305 * Metadata for setting create function.
307 * @param array $params
308 * Parameters as passed to the API.
310 function _civicrm_api3_setting_get_spec(&$params) {
311 $params['domain_id'] = [
312 'api.default' => 'current_domain',
313 'title' => 'Setting Domain',
314 'description' => 'if you do not pass in a domain id this will default to the current domain',
317 'title' => 'Setting Group',
318 'description' => 'if you know the group defining it will make the api more efficient',
323 * Returns value for specific parameter.
325 * Function requires more fields than 'get' but is intended for
326 * runtime usage & should be quicker
328 * @param array $params
329 * Array of one or more valid.
330 * property_name=>value pairs.
335 function civicrm_api3_setting_getvalue($params) {
336 //$config = CRM_Core_Config::singleton();
337 //if (isset($config->$params['name'])) {
338 // return $config->$params['name'];
340 return CRM_Core_BAO_Setting
::getItem(
342 CRM_Utils_Array
::value('name', $params),
343 CRM_Utils_Array
::value('component_id', $params),
344 CRM_Utils_Array
::value('default_value', $params),
345 CRM_Utils_Array
::value('contact_id', $params),
346 CRM_Utils_Array
::value('domain_id', $params)
351 * Metadata for setting create function.
353 * @param array $params
354 * Parameters as passed to the API.
356 function _civicrm_api3_setting_getvalue_spec(&$params) {
359 'title' => 'Settings Group',
360 'api.required' => TRUE,
363 'title' => 'Setting Name',
364 'api.aliases' => ['return'],
366 $params['default_value'] = [
367 'title' => 'Default Value',
369 $params['component_id'] = [
370 'title' => 'Component Id',
372 $params['contact_id'] = [
373 'title' => 'Contact Id',
375 $params['domain_id'] = [
376 'title' => 'Setting Domain',
377 'description' => 'if you do not pass in a domain id this will default to the current domain',
382 * Converts domain input into an array.
384 * If an array is passed in this is used, if 'all' is passed
385 * in this is converted to 'all arrays'
387 * Really domain_id should always be set but doing an empty check because at the moment
388 * using crm-editable will pass an id & default won't be applied
389 * we did talk about id being a pseudonym for domain_id in this api so applying it here.
391 * @param array $params
394 * @throws API_Exception
396 function _civicrm_api3_setting_getDomainArray(&$params) {
397 if (empty($params['domain_id']) && isset($params['id'])) {
398 $params['domain_id'] = $params['id'];
401 if ($params['domain_id'] === 'current_domain') {
402 $params['domain_id'] = CRM_Core_Config
::domainID();
405 if ($params['domain_id'] === 'all') {
406 $domainAPIResult = civicrm_api('domain', 'get', ['version' => 3, 'return' => 'id']);
407 if (isset($domainAPIResult['values'])) {
408 $params['domain_id'] = array_keys($domainAPIResult['values']);
411 throw new API_Exception('All domains not retrieved - problem with Domain Get api call ' . $domainAPIResult['error_message']);
414 if (is_array($params['domain_id'])) {
415 $domains = $params['domain_id'];
418 $domains = [$params['domain_id']];