3 +--------------------------------------------------------------------+
4 | CiviCRM version 4.6 |
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2015 |
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
),
50 'title' => 'Setting Group',
51 'description' => 'Settings Group. This is required if the setting is not stored in config',
52 'type' => CRM_Utils_Type
::T_STRING
),
54 return civicrm_api3_create_success($result, $params, 'Setting', 'getfields');
56 if (!empty($params['name'])) {
57 //am of two minds about special handling for 'name' as opposed to other filters - but is does make most common
59 $params['filters']['name'] = $params['name'];
61 $result = CRM_Core_BAO_Setting
::getSettingSpecification(
62 CRM_Utils_Array
::value('component_id', $params),
63 CRM_Utils_Array
::value('filters', $params, array()),
64 CRM_Utils_Array
::value('domain_id', $params, NULL),
65 CRM_Utils_Array
::value('profile', $params, NULL)
67 // find any supplemental information
68 if (!empty($params['action'])) {
69 $specFunction = '_civicrm_api3_setting_' . strtolower($params['action']) . '_spec';
70 if (function_exists($specFunction)) {
71 $specFunction($result);
74 return civicrm_api3_create_success($result, $params, 'Setting', 'getfields');
78 * Alter metadata for getfields functions.
80 * @param array $params
82 function _civicrm_api3_setting_getfields_spec(&$params) {
83 $params['filters'] = array(
85 'description' => 'Fields you wish to filter by e.g. array("group_name" => "CiviCRM Preferences")',
87 $params['component_id'] = array(
88 'title' => 'Component ID',
89 'description' => 'ID of relevant component',
91 $params['profile'] = array(
93 'description' => 'Profile is passed through to hooks & added to cachestring',
98 * Return default values for settings.
100 * We will domain key this as it could vary by domain (ie. urls)
101 * as we will be creating the option for a function rather than an value to be in the defaults
102 * Note that is not in place as yet.
104 * @param array $params
107 * @throws \CiviCRM_API3_Exception
110 function civicrm_api3_setting_getdefaults(&$params) {
111 $settings = civicrm_api3('Setting', 'getfields', $params);
112 $domains = _civicrm_api3_setting_getDomainArray($params);
114 foreach ($domains as $domainID) {
115 $defaults[$domainID] = array();
116 $noDefaults = array();
117 foreach ($settings['values'] as $setting => $spec) {
118 if (array_key_exists('default', $spec) && !is_null($spec['default'])) {
119 $defaults[$domainID][$setting] = $spec['default'];
122 $noDefaults[$setting] = 1;
125 if (!empty($params['debug'])) {
126 // we are only tracking 'noDefaults' to help us check the xml
127 print_r($noDefaults);
130 return civicrm_api3_create_success($defaults, $params, 'Setting', 'getfields');
133 * Metadata for Setting create function.
135 * @param array $params
136 * Parameters as passed to the API.
138 function _civicrm_api3_setting_getdefaults_spec(&$params) {
139 $params['domain_id'] = array(
140 'api.default' => 'current_domain',
141 'description' => 'Defaults may differ by domain - if you do not pass in a domain id this will default to the current domain
142 an array or "all" are acceptable values for multiple domains',
143 'title' => 'Setting Domain',
148 * Revert settings to defaults.
150 * @param array $params
155 function civicrm_api3_setting_revert(&$params) {
156 $defaults = civicrm_api('Setting', 'getdefaults', $params);
157 $fields = civicrm_api('Setting', 'getfields', $params);
158 $fields = $fields['values'];
159 $domains = _civicrm_api3_setting_getDomainArray($params);
161 foreach ($domains as $domainID) {
162 $valuesToRevert = array_intersect_key($defaults['values'][$domainID], $fields);
163 if (!empty($valuesToRevert)) {
164 $valuesToRevert['version'] = $params['version'];
165 $valuesToRevert['domain_id'] = $domainID;
166 // note that I haven't looked at how the result would appear with multiple domains in play
167 $result = array_merge($result, civicrm_api('Setting', 'create', $valuesToRevert));
171 return civicrm_api3_create_success($result, $params, 'Setting', 'revert');
175 * Alter metadata for getfields functions.
177 * @param array $params
179 function _civicrm_api3_setting_revert_spec(&$params) {
180 $params['name'] = array(
182 'description' => 'Setting Name belongs to',
184 $params['component_id'] = array(
185 'title' => 'Component ID',
186 'description' => 'ID of relevant component',
188 $params['domain_id'] = array(
189 'api.default' => 'current_domain',
190 'description' => 'Defaults may differ by domain - if you do not pass in a domain id this will default to the current domain'
191 . ' an array or "all" are acceptable values for multiple domains',
192 'title' => 'Setting Domain',
197 * Revert settings to defaults.
199 * @param array $params
202 * @throws \CiviCRM_API3_Exception
205 function civicrm_api3_setting_fill(&$params) {
206 $defaults = civicrm_api3('Setting', 'getdefaults', $params);
207 $domains = _civicrm_api3_setting_getDomainArray($params);
209 foreach ($domains as $domainID) {
211 'version' => $params['version'],
212 'domain_id' => $domainID,
214 $existing = civicrm_api3('Setting', 'get', $apiArray);
215 $valuesToFill = array_diff_key($defaults['values'][$domainID], $existing['values'][$domainID]);
216 if (!empty($valuesToFill)) {
217 $result = array_merge($result, civicrm_api('Setting', 'create', $valuesToFill +
$apiArray));
220 return civicrm_api3_create_success($result, $params, 'Setting', 'fill');
224 * Alter metadata for getfields functions.
226 * @param array $params
228 function _civicrm_api3_setting_fill_spec(&$params) {
229 $params['name'] = array(
231 'description' => 'Setting Name belongs to',
233 $params['component_id'] = array(
234 'title' => 'Component ID',
235 'description' => 'ID of relevant component',
237 $params['domain_id'] = array(
238 'api.default' => 'current_domain',
239 'title' => 'Setting Domain',
240 'description' => 'Defaults may differ by domain - if you do not pass in a domain id this will default to the '
241 . 'current domain, an array or "all" are acceptable values for multiple domains',
246 * Create or update a setting.
248 * @param array $params
249 * Parameters as per getfields.
254 function civicrm_api3_setting_create($params) {
255 $domains = _civicrm_api3_setting_getDomainArray($params);
256 $result = CRM_Core_BAO_Setting
::setItems($params, $domains);
257 return civicrm_api3_create_success($result, $params, 'Setting', 'create');
261 * Metadata for setting create function.
263 * @param array $params
264 * Parameters as passed to the API.
266 function _civicrm_api3_setting_create_spec(&$params) {
267 $params['domain_id'] = array(
268 'api.default' => 'current_domain',
269 'title' => 'Setting Domain',
270 'description' => 'if you do not pass in a domain id this will default to the current domain
271 an array or "all" are acceptable values for multiple domains',
273 $params['group'] = array(
274 'title' => 'Setting Group',
275 'description' => 'if you know the group defining it will make the api more efficient',
280 * Returns array of settings matching input parameters.
282 * @param array $params
283 * Array of one or more valid property_name=>value pairs.
286 * Array of matching settings
288 function civicrm_api3_setting_get($params) {
289 $domains = _civicrm_api3_setting_getDomainArray($params);
290 $result = $result = CRM_Core_BAO_Setting
::getItems($params, $domains, CRM_Utils_Array
::value('return', $params, array()));
291 return civicrm_api3_create_success($result, $params, 'Setting', 'get');
294 * Metadata for setting create function.
296 * @param array $params
297 * Parameters as passed to the API.
299 function _civicrm_api3_setting_get_spec(&$params) {
300 $params['domain_id'] = array(
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',
305 $params['group'] = array(
306 'title' => 'Setting Group',
307 'description' => 'if you know the group defining it will make the api more efficient',
311 * Returns value for specific parameter.
313 * Function requires more fields than 'get' but is intended for
314 * runtime usage & should be quicker
316 * @param array $params
317 * Array of one or more valid.
318 * property_name=>value pairs.
323 function civicrm_api3_setting_getvalue($params) {
324 $config = CRM_Core_Config
::singleton();
325 if (isset($config->$params['name'])) {
326 return $config->$params['name'];
328 return CRM_Core_BAO_Setting
::getItem(
330 CRM_Utils_Array
::value('name', $params),
331 CRM_Utils_Array
::value('component_id', $params),
332 CRM_Utils_Array
::value('default_value', $params),
333 CRM_Utils_Array
::value('contact_id', $params),
334 CRM_Utils_Array
::value('domain_id', $params)
339 * Metadata for setting create function.
341 * @param array $params
342 * Parameters as passed to the API.
344 function _civicrm_api3_setting_getvalue_spec(&$params) {
346 $params['group'] = array(
347 'title' => 'Settings Group',
348 'api.required' => TRUE,
350 $params['name'] = array(
351 'title' => 'Setting Name',
352 'api.aliases' => array('return'),
354 $params['default_value'] = array(
355 'title' => 'Default Value',
357 $params['component_id'] = array(
358 'title' => 'Component Id',
360 $params['contact_id'] = array(
361 'title' => 'Contact Id',
363 $params['domain_id'] = array(
364 'title' => 'Setting Domain',
365 'description' => 'if you do not pass in a domain id this will default to the current domain',
370 * Converts domain input into an array.
372 * If an array is passed in this is used, if 'all' is passed
373 * in this is converted to 'all arrays'
375 * Really domain_id should always be set but doing an empty check because at the moment
376 * using crm-editable will pass an id & default won't be applied
377 * we did talk about id being a pseudonym for domain_id in this api so applying it here.
379 * @param array $params
384 function _civicrm_api3_setting_getDomainArray(&$params) {
385 if (empty($params['domain_id']) && isset($params['id'])) {
386 $params['domain_id'] = $params['id'];
389 if ($params['domain_id'] == 'current_domain') {
390 $params['domain_id'] = CRM_Core_Config
::domainID();
393 if ($params['domain_id'] == 'all') {
394 $domainAPIResult = civicrm_api('domain', 'get', array('version' => 3, 'return' => 'id'));
395 if (isset($domainAPIResult['values'])) {
396 $params['domain_id'] = array_keys($domainAPIResult['values']);
399 throw new Exception('All domains not retrieved - problem with Domain Get api call ' . $domainAPIResult['error_message']);
402 if (is_array($params['domain_id'])) {
403 $domains = $params['domain_id'];
406 $domains = array($params['domain_id']);