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  *
  19  * @return array|int|Civi\Api4\Generic\Result
  20  */
  21 function civicrm_api(string $entity, string $action, array $params) {
  22   return \Civi::service('civi_api_kernel')->runSafe($entity, $action, $params);
  23 }
  24
  25 /**
  26  * CiviCRM API version 4.
  27  *
  28  * This API (Application Programming Interface) is used to access and manage data in CiviCRM.
  29  *
  30  * APIv4 is the latest stable version.
  31  *
  32  * @see https://docs.civicrm.org/dev/en/latest/api/v4/usage/
  33  *
  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');`
  38  *
  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');`
  41  *
  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.
  45  *
  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.
  57  *
  58  * @return \Civi\Api4\Generic\Result
  59  * @throws \API_Exception
  60  * @throws \Civi\API\Exception\NotImplementedException
  61  */
  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;
  65
  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;
  70   }
  71   $apiCall = \Civi\API\Request::create($entity, $action, ['version' => 4] + $params);
  72
  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);
  81       }
  82     }
  83   }
  84
  85   $result = $apiCall->execute();
  86
  87   // Index results by key
  88   if ($indexField) {
  89     $result->indexBy($indexField);
  90     if ($removeIndexField) {
  91       foreach ($result as $key => $value) {
  92         unset($result[$key][$indexField]);
  93       }
  94     }
  95   }
  96   // Return result at index
  97   elseif (CRM_Utils_Rule::integer($index)) {
  98     $item = $result->itemAt($index);
  99     if (is_null($item)) {
 100       throw new \API_Exception("Index $index not found in api results");
 101     }
 102     // Attempt to return a Result object if item is array, otherwise just return the item
 103     if (!is_array($item)) {
 104       return $item;
 105     }
 106     $result->exchangeArray($item);
 107   }
 108   if (!empty($indexCol)) {
 109     $result->exchangeArray($result->column($indexCol));
 110   }
 111   return $result;
 112 }
 113
 114 /**
 115  * Version 3 wrapper for civicrm_api.
 116  *
 117  * Throws exception.
 118  *
 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.
 125  *
 126  * @throws CiviCRM_API3_Exception
 127  *
 128  * @return array
 129  */
 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);
 135   }
 136   return $result;
 137 }
 138
 139 /**
 140  * Call getfields from api wrapper.
 141  *
 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.
 145  *
 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
 149  *
 150  * @todo other output modifiers include contact_type
 151  *
 152  * @param array $apiRequest
 153  *
 154  * @return array
 155  *   getfields output
 156  */
 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']);
 164     }
 165     return ['action' => ['api.aliases' => ['api_action']]];
 166   }
 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'];
 171   }
 172   $fields = civicrm_api3($entity, 'getfields', $getFieldsParams);
 173   return $fields['values'];
 174 }
 175
 176 /**
 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.
 181  *
 182  * @param $result
 183  *
 184  * @return bool
 185  *   true if error, false otherwise
 186  */
 187 function civicrm_error($result) {
 188   return is_array($result) && !empty($result['is_error']);
 189 }
 190
 191 /**
 192  * Get camel case version of entity name.
 193  *
 194  * @param string|null $entity
 195  *
 196  * @return string|null
 197  */
 198 function _civicrm_api_get_camel_name($entity) {
 199   return is_string($entity) ? \Civi\API\Request::normalizeEntityName($entity) : NULL;
 200 }
 201
 202 /**
 203  * Swap out any $values vars.
 204  *
 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'
 209  *
 210  * @param array $params
 211  * @param array $parentResult
 212  * @param string $separator
 213  */
 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.
 218       continue;
 219     }
 220     if (is_string($value) && substr($value, 0, 6) == '$value') {
 221       $value = _civicrm_api_replace_variable($value, $parentResult, $separator);
 222     }
 223     // Handle the operator syntax: array('OP' => $val)
 224     elseif (is_array($value) && is_string(reset($value)) && substr(reset($value), 0, 6) == '$value') {
 225       $key = key($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) {
 229         $value = '';
 230       }
 231     }
 232   }
 233 }
 234
 235 /**
 236  * Swap out a $value.foo variable with the value from parent api results.
 237  *
 238  * Called by _civicrm_api_replace_variables to do the substitution.
 239  *
 240  * @param string $value
 241  * @param array $parentResult
 242  * @param string $separator
 243  * @return mixed|null
 244  */
 245 function _civicrm_api_replace_variable($value, $parentResult, $separator) {
 246   $valueSubstitute = substr($value, 7);
 247
 248   if (!empty($parentResult[$valueSubstitute])) {
 249     return $parentResult[$valueSubstitute];
 250   }
 251   else {
 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.
 255     $value = NULL;
 256
 257     $fieldname = array_shift($stringParts);
 258
 259     //when our string is an array we will treat it as an array from that . onwards
 260     $count = count($stringParts);
 261     while ($count > 0) {
 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;
 267         }
 268         $value = $arrayLocation;
 269       }
 270       $count = count($stringParts);
 271     }
 272   }
 273   return $value;
 274 }
 275
 276 /**
 277  * Convert possibly camel name to underscore separated entity name.
 278  *
 279  * @param string $entity
 280  *   Entity name in various formats e.g. Contribution, contribution,
 281  *   OptionValue, option_value, UFJoin, uf_join.
 282  *
 283  * @return string
 284  *   Entity name in underscore separated format.
 285  *
 286  * @deprecated
 287  */
 288 function _civicrm_api_get_entity_name_from_camel($entity) {
 289   if (!$entity) {
 290     // @todo - this should not be called when empty.
 291     return '';
 292   }
 293   return CRM_Core_DAO_AllCoreTables::convertEntityNameToLower($entity);
 294 }
 295
 296 /**
 297  * Having a DAO object find the entity name.
 298  *
 299  * @param CRM_Core_DAO $bao
 300  *   DAO being passed in.
 301  *
 302  * @return string
 303  */
 304 function _civicrm_api_get_entity_name_from_dao($bao) {
 305   return CRM_Core_DAO_AllCoreTables::getBriefName(get_class($bao));
 306 }