3 +--------------------------------------------------------------------+
4 | CiviCRM version 4.3 |
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2013 |
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 * File for CiviCRM APIv3 settings
31 * @package CiviCRM_APIv3_Core
32 * @subpackage API_Settings
33 * @copyright CiviCRM LLC (c) 2004-2013
34 * @version $Id: Settings.php
38 function civicrm_api3_setting_getfields($params) {
39 if(!empty($params['action']) && strtolower($params['action']) == 'getvalue'){
42 'title' => 'name of setting field',
44 'type' => CRM_Utils_Type
::T_STRING
),
45 'group' => array('title' => 'name of setting field',
47 'description' => 'Settings Group. This is required if the setting is not stored in config',
48 'type' => CRM_Utils_Type
::T_STRING
)
50 return civicrm_api3_create_success($result, $params, 'setting', 'getfields');
52 if(!empty($params['name'])){
53 //am of two minds about special handling for 'name' as opposed to other filters - but is does make most common
55 $params['filters']['name'] = $params['name'];
57 $result = CRM_Core_BAO_Setting
::getSettingSpecification(
58 CRM_Utils_Array
::value('component_id',$params),
59 CRM_Utils_Array
::value('filters', $params, array()),
60 CRM_Utils_Array
::value('domain_id', $params, null),
61 CRM_Utils_Array
::value('profile', $params, null)
63 // find any supplemental information
64 if(CRM_Utils_Array
::value('action',$params)){
65 $specFunction = '_civicrm_api3_setting_' . strtolower($params['action']) . '_spec';
66 if (function_exists($specFunction)) {
67 $specFunction($result);
70 return civicrm_api3_create_success($result, $params, 'setting', 'getfields');
73 * Alter metadata for getfields functions
75 function _civicrm_api3_setting_getfields_spec(&$params) {
76 $params['filters'] = array('title' => 'Fields you wish to filter by e.g. array("group_name" => "CiviCRM Preferences")');
77 $params['component_id'] = array('title' => 'id of relevant component');
78 $params['profile'] = array('title' => 'profile is passed through to hooks & added to cachestring');
81 * Return default values for settings. We will domain key this as it could vary by domain (ie. urls)
82 * as we will be creating the option for a function rather than an value to be in the defaults
83 * Note that is not in place as yet
85 function civicrm_api3_setting_getdefaults(&$params){
86 $settings = civicrm_api('setting','getfields', $params);
87 $domains = _civicrm_api3_setting_getDomainArray($params);
89 foreach ($domains as $domainID){
90 $defaults[$domainID] = array();
91 $noDefaults = array();
92 foreach ($settings['values'] as $setting => $spec){
93 if(array_key_exists('default', $spec) && !is_null($spec['default'])){
94 $defaults[$domainID][$setting] = $spec['default'];
97 $noDefaults[$setting] = 1;
100 if(!empty($params['debug'])){
101 // we are only tracking 'noDefaults' to help us check the xml
102 print_r($noDefaults);
105 return civicrm_api3_create_success($defaults,$params,'setting','getfields');
108 * Metadata for setting create function
110 * @param array $params parameters as passed to the API
112 function _civicrm_api3_setting_getdefaults_spec(&$params) {
113 $params['domain_id'] = array(
114 'api.default' => 'current_domain',
115 'description' => 'Defaults may differ by domain - if you do not pass in a domain id this will default to the current domain
116 an array or "all" are acceptable values for multiple domains'
120 * Revert settings to defaults
122 function civicrm_api3_setting_revert(&$params){
123 $defaults = civicrm_api('setting','getdefaults', $params);
124 $fields = civicrm_api('setting','getfields', $params);
125 $fields = $fields['values'];
126 $domains = _civicrm_api3_setting_getDomainArray($params);
128 foreach ($domains as $domainID){
129 $valuesToRevert = array_intersect_key($defaults['values'][$domainID], $fields);
130 if(!empty($valuesToRevert)){
131 $valuesToRevert['version'] = $params['version'];
132 $valuesToRevert['domain_id'] = $domainID;
133 // note that I haven't looked at how the result would appear with multiple domains in play
134 $result = array_merge($result, civicrm_api('setting', 'create', $valuesToRevert));
138 return civicrm_api3_create_success($result, $params, 'setting', 'revert');
141 * Alter metadata for getfields functions
143 function _civicrm_api3_setting_revert_spec(&$params) {
144 $params['name'] = array('title' => 'Setting Name belongs to');
145 $params['component_id'] = array('title' => 'id of relevant component');
146 $params['domain_id'] = array(
147 'api.default' => 'current_domain',
148 'description' => 'Defaults may differ by domain - if you do not pass in a domain id this will default to the current domain
149 an array or "all" are acceptable values for multiple domains'
154 * Revert settings to defaults
156 function civicrm_api3_setting_fill(&$params){
157 $defaults = civicrm_api('setting','getdefaults', $params);
158 $domains = _civicrm_api3_setting_getDomainArray($params);
160 foreach ($domains as $domainID){
162 'version' => $params['version'],
163 'domain_id' => $domainID
165 $existing = civicrm_api('setting','get', $apiArray);
166 $valuesToFill = array_diff_key($defaults['values'][$domainID], $existing['values'][$domainID]);
167 if(!empty($valuesToFill)){
168 $result = array_merge($result, civicrm_api('setting', 'create', $valuesToFill +
$apiArray));
171 return civicrm_api3_create_success($result, $params, 'setting', 'fill');
174 * Alter metadata for getfields functions
176 function _civicrm_api3_setting_fill_spec(&$params) {
177 $params['name'] = array('title' => 'Setting Name belongs to');
178 $params['component_id'] = array('title' => 'id of relevant component');
179 $params['domain_id'] = array(
180 'api.default' => 'current_domain',
181 'description' => 'Defaults may differ by domain - if you do not pass in a domain id this will default to the current domain
182 an array or "all" are acceptable values for multiple domains'
187 * Create or update a setting
189 * @param array $params Associative array of setting
190 * name/value pairs + other vars as applicable - see getfields for more
191 * @example SettingCreate.php Std Create example
193 * @return array api result array
194 * {@getfields setting_create}
197 function civicrm_api3_setting_create($params) {
198 $domains = _civicrm_api3_setting_getDomainArray($params);
199 $result = CRM_Core_BAO_Setting
::setItems($params, $domains);
200 return civicrm_api3_create_success($result,$params,'setting','create');
203 * Metadata for setting create function
205 * @param array $params parameters as passed to the API
207 function _civicrm_api3_setting_create_spec(&$params) {
208 $params['domain_id'] = array(
209 'api.default' => 'current_domain',
210 'description' => 'if you do not pass in a domain id this will default to the current domain
211 an array or "all" are acceptable values for multiple domains'
213 $params['group'] = array(
214 'description' => 'if you know the group defining it will make the api more efficient'
220 * Returns array of settings matching input parameters
222 * @param array $params (referance) Array of one or more valid
223 * property_name=>value pairs.
225 * @return array Array of matching settings
226 * {@getfields setting_get}
229 function civicrm_api3_setting_get($params) {
230 $domains = _civicrm_api3_setting_getDomainArray($params);
231 $result = $result = CRM_Core_BAO_Setting
::getItems($params, $domains, CRM_Utils_Array
::value('return', $params, array()));
232 return civicrm_api3_create_success($result,$params,'setting','get');
235 * Metadata for setting create function
237 * @param array $params parameters as passed to the API
239 function _civicrm_api3_setting_get_spec(&$params) {
240 $params['domain_id'] = array(
241 'api.default' => 'current_domain',
242 'description' => 'if you do not pass in a domain id this will default to the current domain'
244 $params['group'] = array(
245 'description' => 'if you know the group defining it will make the api more efficient'
250 * Returns value for specific parameter. Function requires more fields than 'get' but is intended for
251 * runtime usage & should be quicker
253 * @param array $params (reference) Array of one or more valid
254 * property_name=>value pairs.
256 * @return array Array of matching settings
257 * {@getfields setting_get}
260 function civicrm_api3_setting_getvalue($params) {
261 $config = CRM_Core_Config
::singleton();
262 if(isset($config->$params['name'])){
263 return $config->$params['name'];
265 return CRM_Core_BAO_Setting
::getItem(
267 CRM_Utils_Array
::value('name', $params),
268 CRM_Utils_Array
::value('component_id', $params),
269 CRM_Utils_Array
::value('default_value', $params),
270 CRM_Utils_Array
::value('contact_id', $params),
271 CRM_Utils_Array
::value('domain_id', $params)
276 * Metadata for setting create function
278 * @param array $params parameters as passed to the API
280 function _civicrm_api3_setting_getvalue_spec(&$params) {
282 $params['group'] = array(
283 'title' => 'Settings Group',
284 'api.required' => TRUE,
286 $params['name'] = array(
287 'title' => 'Setting Name',
288 'api.aliases' => array('return'),
290 $params['default_value'] = array(
291 'title' => 'Default Value',
293 $params['component_id'] = array(
294 'title' => 'Component Id',
296 $params['contact_id'] = array(
297 'title' => 'Contact Id',
299 $params['domain_id'] = array(
300 'description' => 'if you do not pass in a domain id this will default to the current domain'
304 * Converts domain input into an array. If an array is passed in this is used, if 'all' is passed
305 * in this is converted to 'all arrays'
307 * Really domain_id should always be set but doing an empty check because at the moment
308 * using crm-editable will pass an id & default won't be applied
309 * we did talk about id being a pseudonym for domain_id in this api so applying it here
311 function _civicrm_api3_setting_getDomainArray(&$params){
312 if(empty($params['domain_id']) && isset($params['id'])){
313 $params['domain_id'] = $params['id'];
316 if($params['domain_id'] == 'current_domain'){
317 $params['domain_id'] = CRM_Core_Config
::domainID();
320 if($params['domain_id'] == 'all'){
321 $domainAPIResult = civicrm_api('domain','get',array('version' => 3, 'return' => 'id'));
322 if (isset($domainAPIResult['values'])) {
323 $params['domain_id'] = array_keys($domainAPIResult['values']);
326 throw new Exception('All domains not retrieved - problem with Domain Get api call ' . $domainAPIResult['error_message']);
329 if(is_array($params['domain_id'])){
330 $domains = $params['domain_id'];
333 $domains = array($params['domain_id']);