4 * @file CiviCRM APIv3 API wrapper.
6 * @package CiviCRM_APIv3
10 * CiviCRM API wrapper function.
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
22 function civicrm_api($entity, $action, array $params, $extra = NULL) {
23 return \Civi
::service('civi_api_kernel')->runSafe($entity, $action, $params, $extra);
27 * Procedural wrapper for the OO api version 4.
29 * @param string $entity
30 * @param string $action
31 * @param array $params
32 * @param string|int $index
33 * If $index is a string, the results array will be indexed by that key.
34 * If $index is an integer, only the result at that index will be returned.
36 * @return \Civi\Api4\Generic\Result
37 * @throws \API_Exception
38 * @throws \Civi\API\Exception\NotImplementedException
40 function civicrm_api4($entity, $action, array $params = [], $index = NULL) {
41 $apiCall = \Civi\Api4\Utils\ActionUtil
::getAction($entity, $action);
42 foreach ($params as $name => $param) {
43 $setter = 'set' . ucfirst($name);
44 $apiCall->$setter($param);
46 $result = $apiCall->execute();
48 // Index results by key
49 if ($index && is_string($index) && !CRM_Utils_Rule
::integer($index)) {
50 $result->indexBy($index);
52 // Return result at index
53 if (CRM_Utils_Rule
::integer($index)) {
54 $item = $result->itemAt($index);
56 throw new \
API_Exception("Index $index not found in api results");
58 // Attempt to return a Result object if item is array, otherwise just return the item
59 if (!is_array($item)) {
62 $result->exchangeArray($item);
69 * Version 3 wrapper for civicrm_api.
73 * @param string $entity
74 * Type of entities to deal with.
75 * @param string $action
76 * Create, get, delete or some special action name.
77 * @param array $params
78 * Array to be passed to function.
80 * @throws CiviCRM_API3_Exception
84 function civicrm_api3($entity, $action, array $params = []) {
85 $params['version'] = 3;
86 $result = \Civi
::service('civi_api_kernel')->runSafe($entity, $action, $params);
87 if (is_array($result) && !empty($result['is_error'])) {
88 throw new CiviCRM_API3_Exception($result['error_message'], CRM_Utils_Array
::value('error_code', $result, 'undefined'), $result);
94 * Call getfields from api wrapper.
96 * This function ensures that settings that
97 * could alter getfields output (e.g. action for all api & profile_id for
98 * profile api ) are consistently passed in.
100 * We check whether the api call is 'getfields' because if getfields is
101 * being called we return an empty array as no alias swapping, validation or
102 * default filling is done on getfields & we want to avoid a loop
104 * @todo other output modifiers include contact_type
106 * @param array $apiRequest
111 function _civicrm_api3_api_getfields(&$apiRequest) {
112 if (strtolower($apiRequest['action'] == 'getfields')) {
113 // the main param getfields takes is 'action' - however this param is not compatible with REST
114 // so we accept 'api_action' as an alias of action on getfields
115 if (!empty($apiRequest['params']['api_action'])) {
116 // $apiRequest['params']['action'] = $apiRequest['params']['api_action'];
117 // unset($apiRequest['params']['api_action']);
119 return ['action' => ['api.aliases' => ['api_action']]];
121 $getFieldsParams = ['action' => $apiRequest['action']];
122 $entity = $apiRequest['entity'];
123 if ($entity == 'Profile' && array_key_exists('profile_id', $apiRequest['params'])) {
124 $getFieldsParams['profile_id'] = $apiRequest['params']['profile_id'];
126 $fields = civicrm_api3($entity, 'getfields', $getFieldsParams);
127 return $fields['values'];
131 * Check if the result is an error. Note that this function has been retained from
132 * api v2 for convenience but the result is more standardised in v3 and param
133 * 'format.is_success' => 1
134 * will result in a boolean success /fail being returned if that is what you need.
139 * true if error, false otherwise
141 function civicrm_error($result) {
142 if (is_array($result)) {
143 return (array_key_exists('is_error', $result) &&
151 * Get camel case version of entity name.
153 * @param string|null $entity
155 * @return string|null
157 function _civicrm_api_get_camel_name($entity) {
158 return is_string($entity) ? CRM_Utils_String
::convertStringToCamel($entity) : NULL;
162 * Swap out any $values vars.
164 * Ie. the value after $value is swapped for the parent $result
165 * 'activity_type_id' => '$value.testfield',
166 * 'tag_id' => '$value.api.tag.create.id',
167 * 'tag1_id' => '$value.api.entity.create.0.id'
169 * @param array $params
170 * @param array $parentResult
171 * @param string $separator
173 function _civicrm_api_replace_variables(&$params, &$parentResult, $separator = '.') {
174 foreach ($params as $field => &$value) {
175 if (substr($field, 0, 4) == 'api.') {
176 // CRM-21246 - Leave nested calls alone.
179 if (is_string($value) && substr($value, 0, 6) == '$value') {
180 $value = _civicrm_api_replace_variable($value, $parentResult, $separator);
182 // Handle the operator syntax: array('OP' => $val)
183 elseif (is_array($value) && is_string(reset($value)) && substr(reset($value), 0, 6) == '$value') {
185 $value[$key] = _civicrm_api_replace_variable($value[$key], $parentResult, $separator);
186 // A null value with an operator will cause an error, so remove it.
187 if ($value[$key] === NULL) {
195 * Swap out a $value.foo variable with the value from parent api results.
197 * Called by _civicrm_api_replace_variables to do the substitution.
199 * @param string $value
200 * @param array $parentResult
201 * @param string $separator
204 function _civicrm_api_replace_variable($value, $parentResult, $separator) {
205 $valueSubstitute = substr($value, 7);
207 if (!empty($parentResult[$valueSubstitute])) {
208 return $parentResult[$valueSubstitute];
211 $stringParts = explode($separator, $value);
212 unset($stringParts[0]);
213 // CRM-16168 If we have failed to swap it out we should unset it rather than leave the placeholder.
216 $fieldname = array_shift($stringParts);
218 //when our string is an array we will treat it as an array from that . onwards
219 $count = count($stringParts);
221 $fieldname .= "." . array_shift($stringParts);
222 if (array_key_exists($fieldname, $parentResult) && is_array($parentResult[$fieldname])) {
223 $arrayLocation = $parentResult[$fieldname];
224 foreach ($stringParts as $key => $innerValue) {
225 $arrayLocation = CRM_Utils_Array
::value($innerValue, $arrayLocation);
227 $value = $arrayLocation;
229 $count = count($stringParts);
236 * Convert possibly camel name to underscore separated entity name.
238 * @param string $entity
239 * Entity name in various formats e.g. Contribution, contribution,
240 * OptionValue, option_value, UFJoin, uf_join.
243 * Entity name in underscore separated format.
245 function _civicrm_api_get_entity_name_from_camel($entity) {
246 if (!$entity ||
$entity === strtolower($entity)) {
249 elseif ($entity == 'PCP') {
253 $entity = ltrim(strtolower(str_replace('U_F',
255 // That's CamelCase, beside an odd UFCamel that is expected as uf_camel
256 preg_replace('/(?=[A-Z])/', '_$0', $entity)
263 * Having a DAO object find the entity name.
266 * DAO being passed in.
270 function _civicrm_api_get_entity_name_from_dao($bao) {
271 $daoName = str_replace("BAO", "DAO", get_class($bao));
272 return CRM_Core_DAO_AllCoreTables
::getBriefName($daoName);