3 +--------------------------------------------------------------------+
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2019 |
7 +--------------------------------------------------------------------+
8 | This file is a part of CiviCRM. |
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. |
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. |
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 +--------------------------------------------------------------------+
29 * This api exposes CiviCRM configuration settings.
31 * @package CiviCRM_APIv3
35 * Get fields for setting api calls.
37 * @param array $params
41 function civicrm_api3_setting_getfields($params) {
42 if (!empty($params['action']) && strtolower($params['action']) == 'getvalue') {
45 'title' => 'name of setting field',
47 'type' => CRM_Utils_Type
::T_STRING
,
51 'title' => 'Setting Group',
52 'description' => 'Settings Group. This is required if the setting is not stored in config',
53 'type' => CRM_Utils_Type
::T_STRING
,
56 return civicrm_api3_create_success($result, $params, 'Setting', 'getfields');
58 if (!empty($params['name'])) {
59 //am of two minds about special handling for 'name' as opposed to other filters - but is does make most common
61 $params['filters']['name'] = $params['name'];
63 $result = CRM_Core_BAO_Setting
::getSettingSpecification(
64 CRM_Utils_Array
::value('component_id', $params),
65 CRM_Utils_Array
::value('filters', $params, []),
66 CRM_Utils_Array
::value('domain_id', $params, NULL),
67 CRM_Utils_Array
::value('profile', $params, NULL)
69 // find any supplemental information
70 if (!empty($params['action'])) {
71 $specFunction = '_civicrm_api3_setting_' . strtolower($params['action']) . '_spec';
72 if (function_exists($specFunction)) {
73 $specFunction($result);
76 return civicrm_api3_create_success($result, $params, 'Setting', 'getfields');
80 * Alter metadata for getfields functions.
82 * @param array $params
84 function _civicrm_api3_setting_getfields_spec(&$params) {
85 $params['filters'] = [
87 'description' => 'Fields you wish to filter by e.g. array("group_name" => "CiviCRM Preferences")',
89 $params['component_id'] = [
90 'title' => 'Component ID',
91 'description' => 'ID of relevant component',
93 $params['profile'] = [
95 'description' => 'Profile is passed through to hooks & added to cachestring',
100 * Return default values for settings.
102 * We will domain key this as it could vary by domain (ie. urls)
103 * as we will be creating the option for a function rather than an value to be in the defaults
104 * Note that is not in place as yet.
106 * @param array $params
109 * @throws \CiviCRM_API3_Exception
112 function civicrm_api3_setting_getdefaults(&$params) {
113 $settings = civicrm_api3('Setting', 'getfields', $params);
114 $domains = _civicrm_api3_setting_getDomainArray($params);
116 foreach ($domains as $domainID) {
117 $defaults[$domainID] = [];
118 foreach ($settings['values'] as $setting => $spec) {
119 if (array_key_exists('default', $spec) && !is_null($spec['default'])) {
120 $defaults[$domainID][$setting] = $spec['default'];
124 return civicrm_api3_create_success($defaults, $params, 'Setting', 'getfields');
128 * Metadata for Setting create function.
130 * @param array $params
131 * Parameters as passed to the API.
133 function _civicrm_api3_setting_getdefaults_spec(&$params) {
134 $params['domain_id'] = [
135 'api.default' => 'current_domain',
136 'description' => 'Defaults may differ by domain - if you do not pass in a domain id this will default to the current domain
137 an array or "all" are acceptable values for multiple domains',
138 'title' => 'Setting Domain',
143 * Get options for settings.
145 * @param array $params
148 * @throws \API_Exception
150 function civicrm_api3_setting_getoptions($params) {
151 $specs = CRM_Core_BAO_Setting
::getSettingSpecification();
153 if (empty($specs[$params['field']]) ||
empty($specs[$params['field']]['pseudoconstant'])) {
154 throw new API_Exception("The field '" . $params['field'] . "' has no associated option list.");
157 $pseudoconstant = $specs[$params['field']]['pseudoconstant'];
159 // It would be nice if we could leverage CRM_Core_PseudoConstant::get() somehow,
160 // but it's tightly coupled to DAO/field. However, if you really need to support
161 // more pseudoconstant types, then probably best to refactor it. For now, KISS.
162 if (!empty($pseudoconstant['callback'])) {
163 $values = Civi\Core\Resolver
::singleton()->call($pseudoconstant['callback'], []);
164 return civicrm_api3_create_success($values, $params, 'Setting', 'getoptions');
166 elseif (!empty($pseudoconstant['optionGroupName'])) {
167 $keyColumn = 'value';
168 if (!empty($pseudoconstant['keyColumn'])) {
169 $keyColumn = $pseudoconstant['keyColumn'];
171 return civicrm_api3_create_success(
172 CRM_Core_OptionGroup
::values($pseudoconstant['optionGroupName'], FALSE, FALSE, TRUE, NULL, 'label', TRUE, FALSE, $keyColumn),
173 $params, 'Setting', 'getoptions'
177 throw new API_Exception("The field '" . $params['field'] . "' uses an unsupported option list.");
181 * Revert settings to defaults.
183 * @param array $params
188 function civicrm_api3_setting_revert(&$params) {
189 $defaults = civicrm_api('Setting', 'getdefaults', $params);
190 $fields = civicrm_api('Setting', 'getfields', $params);
191 $fields = $fields['values'];
192 $domains = _civicrm_api3_setting_getDomainArray($params);
194 foreach ($domains as $domainID) {
195 $valuesToRevert = array_intersect_key($defaults['values'][$domainID], $fields);
196 if (!empty($valuesToRevert)) {
197 $valuesToRevert['version'] = $params['version'];
198 $valuesToRevert['domain_id'] = $domainID;
199 // note that I haven't looked at how the result would appear with multiple domains in play
200 $result = array_merge($result, civicrm_api('Setting', 'create', $valuesToRevert));
204 return civicrm_api3_create_success($result, $params, 'Setting', 'revert');
208 * Alter metadata for getfields functions.
210 * @param array $params
212 function _civicrm_api3_setting_revert_spec(&$params) {
215 'description' => 'Setting Name belongs to',
217 $params['component_id'] = [
218 'title' => 'Component ID',
219 'description' => 'ID of relevant component',
221 $params['domain_id'] = [
222 'api.default' => 'current_domain',
223 'description' => 'Defaults may differ by domain - if you do not pass in a domain id this will default to the current domain'
224 . ' an array or "all" are acceptable values for multiple domains',
225 'title' => 'Setting Domain',
230 * Revert settings to defaults.
232 * @param array $params
235 * @throws \CiviCRM_API3_Exception
238 function civicrm_api3_setting_fill(&$params) {
239 $defaults = civicrm_api3('Setting', 'getdefaults', $params);
240 $domains = _civicrm_api3_setting_getDomainArray($params);
242 foreach ($domains as $domainID) {
244 'version' => $params['version'],
245 'domain_id' => $domainID,
247 $existing = civicrm_api3('Setting', 'get', $apiArray);
248 $valuesToFill = array_diff_key($defaults['values'][$domainID], $existing['values'][$domainID]);
249 if (!empty($valuesToFill)) {
250 $result = array_merge($result, civicrm_api('Setting', 'create', $valuesToFill +
$apiArray));
253 return civicrm_api3_create_success($result, $params, 'Setting', 'fill');
257 * Alter metadata for getfields functions.
259 * @param array $params
261 function _civicrm_api3_setting_fill_spec(&$params) {
264 'description' => 'Setting Name belongs to',
266 $params['component_id'] = [
267 'title' => 'Component ID',
268 'description' => 'ID of relevant component',
270 $params['domain_id'] = [
271 'api.default' => 'current_domain',
272 'title' => 'Setting Domain',
273 'description' => 'Defaults may differ by domain - if you do not pass in a domain id this will default to the '
274 . 'current domain, an array or "all" are acceptable values for multiple domains',
279 * Create or update a setting.
281 * @param array $params
282 * Parameters as per getfields.
287 function civicrm_api3_setting_create($params) {
288 $domains = _civicrm_api3_setting_getDomainArray($params);
289 $result = CRM_Core_BAO_Setting
::setItems($params, $domains);
290 return civicrm_api3_create_success($result, $params, 'Setting', 'create');
294 * Metadata for setting create function.
296 * @param array $params
297 * Parameters as passed to the API.
299 function _civicrm_api3_setting_create_spec(&$params) {
300 $params['domain_id'] = [
301 'api.default' => 'current_domain',
302 'title' => 'Setting Domain',
303 'description' => 'if you do not pass in a domain id this will default to the current domain
304 an array or "all" are acceptable values for multiple domains',
307 'title' => 'Setting Group',
308 'description' => 'if you know the group defining it will make the api more efficient',
313 * Returns array of settings matching input parameters.
315 * @param array $params
316 * Array of one or more valid property_name=>value pairs.
319 * Array of matching settings
321 function civicrm_api3_setting_get($params) {
322 $domains = _civicrm_api3_setting_getDomainArray($params);
323 $result = CRM_Core_BAO_Setting
::getItems($params, $domains, CRM_Utils_Array
::value('return', $params, []));
324 return civicrm_api3_create_success($result, $params, 'Setting', 'get');
328 * Metadata for setting create function.
330 * @param array $params
331 * Parameters as passed to the API.
333 function _civicrm_api3_setting_get_spec(&$params) {
334 $params['domain_id'] = [
335 'api.default' => 'current_domain',
336 'title' => 'Setting Domain',
337 'description' => 'if you do not pass in a domain id this will default to the current domain',
340 'title' => 'Setting Group',
341 'description' => 'if you know the group defining it will make the api more efficient',
346 * Returns value for specific parameter.
348 * Function requires more fields than 'get' but is intended for
349 * runtime usage & should be quicker
351 * @param array $params
352 * Array of one or more valid.
353 * property_name=>value pairs.
358 function civicrm_api3_setting_getvalue($params) {
359 //$config = CRM_Core_Config::singleton();
360 //if (isset($config->$params['name'])) {
361 // return $config->$params['name'];
363 return CRM_Core_BAO_Setting
::getItem(
365 CRM_Utils_Array
::value('name', $params),
366 CRM_Utils_Array
::value('component_id', $params),
367 CRM_Utils_Array
::value('default_value', $params),
368 CRM_Utils_Array
::value('contact_id', $params),
369 CRM_Utils_Array
::value('domain_id', $params)
374 * Metadata for setting create function.
376 * @param array $params
377 * Parameters as passed to the API.
379 function _civicrm_api3_setting_getvalue_spec(&$params) {
382 'title' => 'Settings Group',
383 'api.required' => TRUE,
386 'title' => 'Setting Name',
387 'api.aliases' => ['return'],
389 $params['default_value'] = [
390 'title' => 'Default Value',
392 $params['component_id'] = [
393 'title' => 'Component Id',
395 $params['contact_id'] = [
396 'title' => 'Contact Id',
398 $params['domain_id'] = [
399 'title' => 'Setting Domain',
400 'description' => 'if you do not pass in a domain id this will default to the current domain',
405 * Converts domain input into an array.
407 * If an array is passed in this is used, if 'all' is passed
408 * in this is converted to 'all arrays'
410 * Really domain_id should always be set but doing an empty check because at the moment
411 * using crm-editable will pass an id & default won't be applied
412 * we did talk about id being a pseudonym for domain_id in this api so applying it here.
414 * @param array $params
419 function _civicrm_api3_setting_getDomainArray(&$params) {
420 if (empty($params['domain_id']) && isset($params['id'])) {
421 $params['domain_id'] = $params['id'];
424 if ($params['domain_id'] == 'current_domain') {
425 $params['domain_id'] = CRM_Core_Config
::domainID();
428 if ($params['domain_id'] == 'all') {
429 $domainAPIResult = civicrm_api('domain', 'get', ['version' => 3, 'return' => 'id']);
430 if (isset($domainAPIResult['values'])) {
431 $params['domain_id'] = array_keys($domainAPIResult['values']);
434 throw new Exception('All domains not retrieved - problem with Domain Get api call ' . $domainAPIResult['error_message']);
437 if (is_array($params['domain_id'])) {
438 $domains = $params['domain_id'];
441 $domains = [$params['domain_id']];