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
19 * @return array|int|Civi\Api4\Generic\Result
21 function civicrm_api(string $entity, string $action, array $params) {
22 return \Civi
::service('civi_api_kernel')->runSafe($entity, $action, $params);
26 * CiviCRM API version 4.
28 * This API (Application Programming Interface) is used to access and manage data in CiviCRM.
30 * APIv4 is the latest stable version.
32 * @see https://docs.civicrm.org/dev/en/latest/api/v4/usage/
34 * @param string $entity Name of the CiviCRM entity to access.
35 * All entity names are capitalized CamelCase, e.g. `ContributionPage`.
36 * Most entities correspond to a database table (e.g. `Contact` is the table `civicrm_contact`).
37 * For a complete list of available entities, call `civicrm_api4('Entity', 'get');`
39 * @param string $action The "verb" of the api call.
40 * For a complete list of actions for a given entity (e.g. `Contact`), call `civicrm_api4('Contact', 'getActions');`
42 * @param array $params An array of API input keyed by parameter name.
43 * The easiest way to discover all available parameters is to visit the API Explorer on your CiviCRM site.
44 * The API Explorer is listed in the CiviCRM menu under Support -> Developer.
46 * @param string|int|array $index Controls the Result array format.
47 * By default the api Result contains a non-associative array of data. Passing an $index tells the api to
48 * automatically reformat the array, depending on the variable type passed:
49 * - **Integer:** return a single result array;
50 * e.g. `$index = 0` will return the first result, 1 will return the second, and -1 will return the last.
51 * - **String:** index the results by a field value;
52 * e.g. `$index = "name"` will return an associative array with the field 'name' as keys.
53 * - **Non-associative array:** return a single value from each result;
54 * e.g. `$index = ['title']` will return a non-associative array of strings - the 'title' field from each result.
55 * - **Associative array:** a combination of the previous two modes;
56 * e.g. `$index = ['name' => 'title']` will return an array of strings - the 'title' field keyed by the 'name' field.
58 * @return \Civi\Api4\Generic\Result
59 * @throws \API_Exception
60 * @throws \Civi\API\Exception\NotImplementedException
62 function civicrm_api4(string $entity, string $action, array $params = [], $index = NULL) {
63 $indexField = $index && is_string($index) && !CRM_Utils_Rule
::integer($index) ?
$index : NULL;
64 $removeIndexField = FALSE;
66 // If index field is not part of the select query, we add it here and remove it below (except for oddball "Setting" api)
67 if ($indexField && !empty($params['select']) && is_array($params['select']) && !($entity === 'Setting' && $action === 'get') && !\Civi\Api4\Utils\SelectUtil
::isFieldSelected($indexField, $params['select'])) {
68 $params['select'][] = $indexField;
69 $removeIndexField = TRUE;
71 $apiCall = \Civi\API\Request
::create($entity, $action, ['version' => 4] +
$params);
73 if ($index && is_array($index)) {
74 $indexCol = reset($index);
75 $indexField = key($index);
76 // Index array indicates only 1 or 2 fields need to be selected (except for oddball "Setting" api)
77 if ($entity !== 'Setting' && property_exists($apiCall, 'select')) {
78 $apiCall->setSelect([$indexCol]);
79 if ($indexField && $indexField != $indexCol) {
80 $apiCall->addSelect($indexField);
85 $result = $apiCall->execute();
87 // Index results by key
89 $result->indexBy($indexField);
90 if ($removeIndexField) {
91 foreach ($result as $key => $value) {
92 unset($result[$key][$indexField]);
96 // Return result at index
97 elseif (CRM_Utils_Rule
::integer($index)) {
98 $item = $result->itemAt($index);
100 throw new \
API_Exception("Index $index not found in api results");
102 // Attempt to return a Result object if item is array, otherwise just return the item
103 if (!is_array($item)) {
106 $result->exchangeArray($item);
108 if (!empty($indexCol)) {
109 $result->exchangeArray($result->column($indexCol));
115 * Version 3 wrapper for civicrm_api.
119 * @param string $entity
120 * Type of entities to deal with.
121 * @param string $action
122 * Create, get, delete or some special action name.
123 * @param array $params
124 * Array to be passed to function.
126 * @throws CiviCRM_API3_Exception
130 function civicrm_api3(string $entity, string $action, array $params = []) {
131 $params['version'] = 3;
132 $result = \Civi
::service('civi_api_kernel')->runSafe($entity, $action, $params);
133 if (is_array($result) && !empty($result['is_error'])) {
134 throw new CiviCRM_API3_Exception($result['error_message'], CRM_Utils_Array
::value('error_code', $result, 'undefined'), $result);
140 * Call getfields from api wrapper.
142 * This function ensures that settings that
143 * could alter getfields output (e.g. action for all api & profile_id for
144 * profile api ) are consistently passed in.
146 * We check whether the api call is 'getfields' because if getfields is
147 * being called we return an empty array as no alias swapping, validation or
148 * default filling is done on getfields & we want to avoid a loop
150 * @todo other output modifiers include contact_type
152 * @param array $apiRequest
157 function _civicrm_api3_api_getfields(&$apiRequest) {
158 if (strtolower($apiRequest['action'] == 'getfields')) {
159 // the main param getfields takes is 'action' - however this param is not compatible with REST
160 // so we accept 'api_action' as an alias of action on getfields
161 if (!empty($apiRequest['params']['api_action'])) {
162 // $apiRequest['params']['action'] = $apiRequest['params']['api_action'];
163 // unset($apiRequest['params']['api_action']);
165 return ['action' => ['api.aliases' => ['api_action']]];
167 $getFieldsParams = ['action' => $apiRequest['action']];
168 $entity = $apiRequest['entity'];
169 if ($entity == 'Profile' && array_key_exists('profile_id', $apiRequest['params'])) {
170 $getFieldsParams['profile_id'] = $apiRequest['params']['profile_id'];
172 $fields = civicrm_api3($entity, 'getfields', $getFieldsParams);
173 return $fields['values'];
177 * Check if the result is an error. Note that this function has been retained from
178 * api v2 for convenience but the result is more standardised in v3 and param
179 * 'format.is_success' => 1
180 * will result in a boolean success /fail being returned if that is what you need.
185 * true if error, false otherwise
187 function civicrm_error($result) {
188 return is_array($result) && !empty($result['is_error']);
192 * Get camel case version of entity name.
194 * @param string|null $entity
196 * @return string|null
198 function _civicrm_api_get_camel_name($entity) {
199 return is_string($entity) ? \Civi\API\Request
::normalizeEntityName($entity) : NULL;
203 * Swap out any $values vars.
205 * Ie. the value after $value is swapped for the parent $result
206 * 'activity_type_id' => '$value.testfield',
207 * 'tag_id' => '$value.api.tag.create.id',
208 * 'tag1_id' => '$value.api.entity.create.0.id'
210 * @param array $params
211 * @param array $parentResult
212 * @param string $separator
214 function _civicrm_api_replace_variables(&$params, &$parentResult, $separator = '.') {
215 foreach ($params as $field => &$value) {
216 if (substr($field, 0, 4) == 'api.') {
217 // CRM-21246 - Leave nested calls alone.
220 if (is_string($value) && substr($value, 0, 6) == '$value') {
221 $value = _civicrm_api_replace_variable($value, $parentResult, $separator);
223 // Handle the operator syntax: array('OP' => $val)
224 elseif (is_array($value) && is_string(reset($value)) && substr(reset($value), 0, 6) == '$value') {
226 $value[$key] = _civicrm_api_replace_variable($value[$key], $parentResult, $separator);
227 // A null value with an operator will cause an error, so remove it.
228 if ($value[$key] === NULL) {
236 * Swap out a $value.foo variable with the value from parent api results.
238 * Called by _civicrm_api_replace_variables to do the substitution.
240 * @param string $value
241 * @param array $parentResult
242 * @param string $separator
245 function _civicrm_api_replace_variable($value, $parentResult, $separator) {
246 $valueSubstitute = substr($value, 7);
248 if (!empty($parentResult[$valueSubstitute])) {
249 return $parentResult[$valueSubstitute];
252 $stringParts = explode($separator, $value);
253 unset($stringParts[0]);
254 // CRM-16168 If we have failed to swap it out we should unset it rather than leave the placeholder.
257 $fieldname = array_shift($stringParts);
259 //when our string is an array we will treat it as an array from that . onwards
260 $count = count($stringParts);
262 $fieldname .= "." . array_shift($stringParts);
263 if (array_key_exists($fieldname, $parentResult) && is_array($parentResult[$fieldname])) {
264 $arrayLocation = $parentResult[$fieldname];
265 foreach ($stringParts as $key => $innerValue) {
266 $arrayLocation = $arrayLocation[$innerValue] ??
NULL;
268 $value = $arrayLocation;
270 $count = count($stringParts);
277 * Convert possibly camel name to underscore separated entity name.
279 * @param string $entity
280 * Entity name in various formats e.g. Contribution, contribution,
281 * OptionValue, option_value, UFJoin, uf_join.
284 * Entity name in underscore separated format.
288 function _civicrm_api_get_entity_name_from_camel($entity) {
290 // @todo - this should not be called when empty.
293 return CRM_Core_DAO_AllCoreTables
::convertEntityNameToLower($entity);
297 * Having a DAO object find the entity name.
299 * @param CRM_Core_DAO $bao
300 * DAO being passed in.
304 function _civicrm_api_get_entity_name_from_dao($bao) {
305 return CRM_Core_DAO_AllCoreTables
::getBriefName(get_class($bao));