Merge branch 4.5 into 4.6
[civicrm-core.git] / api / api.php
1 <?php
2
3 /**
4 * @file CiviCRM APIv3 API wrapper.
5 *
6 * @package CiviCRM_APIv3
7 */
8
9 /**
10 * CiviCRM API wrapper function.
11 *
12 * @param string $entity
13 * type of entities to deal with
14 * @param string $action
15 * create, get, delete or some special action name.
16 * @param array $params
17 * array to be passed to function
18 * @param null $extra
19 *
20 * @return array|int
21 */
22 function civicrm_api($entity, $action, $params, $extra = NULL) {
23 return \Civi\Core\Container::singleton()->get('civi_api_kernel')->run($entity, $action, $params, $extra);
24 }
25
26 /**
27 * Version 3 wrapper for civicrm_api.
28 *
29 * Throws exception.
30 *
31 * @param string $entity
32 * Type of entities to deal with.
33 * @param string $action
34 * Create, get, delete or some special action name.
35 * @param array $params
36 * Array to be passed to function.
37 *
38 * @throws CiviCRM_API3_Exception
39 * @return array
40 */
41 function civicrm_api3($entity, $action, $params = array()) {
42 $params['version'] = 3;
43 $result = civicrm_api($entity, $action, $params);
44 if (is_array($result) && !empty($result['is_error'])) {
45 throw new CiviCRM_API3_Exception($result['error_message'], CRM_Utils_Array::value('error_code', $result, 'undefined'), $result);
46 }
47 return $result;
48 }
49
50 /**
51 * Call getfields from api wrapper.
52 *
53 * This function ensures that settings that
54 * could alter getfields output (e.g. action for all api & profile_id for
55 * profile api ) are consistently passed in.
56 *
57 * We check whether the api call is 'getfields' because if getfields is
58 * being called we return an empty array as no alias swapping, validation or
59 * default filling is done on getfields & we want to avoid a loop
60 *
61 * @todo other output modifiers include contact_type
62 *
63 * @param array $apiRequest
64 *
65 * @return array
66 * getfields output
67 */
68 function _civicrm_api3_api_getfields(&$apiRequest) {
69 if (strtolower($apiRequest['action'] == 'getfields')) {
70 // the main param getfields takes is 'action' - however this param is not compatible with REST
71 // so we accept 'api_action' as an alias of action on getfields
72 if (!empty($apiRequest['params']['api_action'])) {
73 // $apiRequest['params']['action'] = $apiRequest['params']['api_action'];
74 // unset($apiRequest['params']['api_action']);
75 }
76 return array('action' => array('api.aliases' => array('api_action')));
77 }
78 $getFieldsParams = array('action' => $apiRequest['action']);
79 $entity = $apiRequest['entity'];
80 if ($entity == 'Profile' && array_key_exists('profile_id', $apiRequest['params'])) {
81 $getFieldsParams['profile_id'] = $apiRequest['params']['profile_id'];
82 }
83 $fields = civicrm_api3($entity, 'getfields', $getFieldsParams);
84 return $fields['values'];
85 }
86
87 /**
88 * Check if the result is an error. Note that this function has been retained from
89 * api v2 for convenience but the result is more standardised in v3 and param
90 * 'format.is_success' => 1
91 * will result in a boolean success /fail being returned if that is what you need.
92 *
93 * @param $result
94 *
95 * @return bool
96 * true if error, false otherwise
97 */
98 function civicrm_error($result) {
99 if (is_array($result)) {
100 return (array_key_exists('is_error', $result) &&
101 $result['is_error']
102 ) ? TRUE : FALSE;
103 }
104 return FALSE;
105 }
106
107 /**
108 * Get camel case version of entity name.
109 *
110 * @param string|null $entity
111 *
112 * @return string|null
113 */
114 function _civicrm_api_get_camel_name($entity) {
115 return is_string($entity) ? CRM_Utils_String::convertStringToCamel($entity) : NULL;
116 }
117
118 /**
119 * Swap out any $values vars.
120 *
121 * Ie. the value after $value is swapped for the parent $result
122 * 'activity_type_id' => '$value.testfield',
123 * 'tag_id' => '$value.api.tag.create.id',
124 * 'tag1_id' => '$value.api.entity.create.0.id'
125 *
126 * @param array $params
127 * @param array $parentResult
128 * @param string $separator
129 */
130 function _civicrm_api_replace_variables(&$params, &$parentResult, $separator = '.') {
131
132 foreach ($params as $field => $value) {
133
134 if (is_string($value) && substr($value, 0, 6) == '$value') {
135 $valueSubstitute = substr($value, 7);
136
137 if (!empty($parentResult[$valueSubstitute])) {
138 $params[$field] = $parentResult[$valueSubstitute];
139 }
140 else {
141
142 $stringParts = explode($separator, $value);
143 unset($stringParts[0]);
144
145 $fieldname = array_shift($stringParts);
146
147 //when our string is an array we will treat it as an array from that . onwards
148 $count = count($stringParts);
149 while ($count > 0) {
150 $fieldname .= "." . array_shift($stringParts);
151 if (array_key_exists($fieldname, $parentResult) && is_array($parentResult[$fieldname])) {
152 $arrayLocation = $parentResult[$fieldname];
153 foreach ($stringParts as $key => $innerValue) {
154 $arrayLocation = CRM_Utils_Array::value($innerValue, $arrayLocation);
155 }
156 $params[$field] = $arrayLocation;
157 }
158 $count = count($stringParts);
159 }
160 }
161 }
162 }
163 }
164
165 /**
166 * Convert possibly camel name to underscore separated entity name.
167 *
168 * @param string $entity
169 * Entity name in various formats e.g. Contribution, contribution,
170 * OptionValue, option_value, UFJoin, uf_join.
171 *
172 * @return string
173 * Entity name in underscore separated format.
174 */
175 function _civicrm_api_get_entity_name_from_camel($entity) {
176 if (!$entity || $entity === strtolower($entity)) {
177 return $entity;
178 }
179 else {
180 $entity = ltrim(strtolower(str_replace('U_F',
181 'uf',
182 // That's CamelCase, beside an odd UFCamel that is expected as uf_camel
183 preg_replace('/(?=[A-Z])/', '_$0', $entity)
184 )), '_');
185 }
186 return $entity;
187 }
188
189 /**
190 * Having a DAO object find the entity name.
191 *
192 * @param object $bao
193 * DAO being passed in.
194 *
195 * @return string
196 */
197 function _civicrm_api_get_entity_name_from_dao($bao) {
198 $daoName = str_replace("BAO", "DAO", get_class($bao));
199 return CRM_Core_DAO_AllCoreTables::getBriefName($daoName);
200 }