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::service('civi_api_kernel')->runSafe($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  *
  40  * @return array
  41  */
  42 function civicrm_api3($entity, $action, $params = []) {
  43   $params['version'] = 3;
  44   $result = \Civi::service('civi_api_kernel')->runSafe($entity, $action, $params);
  45   if (is_array($result) && !empty($result['is_error'])) {
  46     throw new CiviCRM_API3_Exception($result['error_message'], CRM_Utils_Array::value('error_code', $result, 'undefined'), $result);
  47   }
  48   return $result;
  49 }
  50
  51 /**
  52  * Call getfields from api wrapper.
  53  *
  54  * This function ensures that settings that
  55  * could alter getfields output (e.g. action for all api & profile_id for
  56  * profile api ) are consistently passed in.
  57  *
  58  * We check whether the api call is 'getfields' because if getfields is
  59  * being called we return an empty array as no alias swapping, validation or
  60  * default filling is done on getfields & we want to avoid a loop
  61  *
  62  * @todo other output modifiers include contact_type
  63  *
  64  * @param array $apiRequest
  65  *
  66  * @return array
  67  *   getfields output
  68  */
  69 function _civicrm_api3_api_getfields(&$apiRequest) {
  70   if (strtolower($apiRequest['action'] == 'getfields')) {
  71     // the main param getfields takes is 'action' - however this param is not compatible with REST
  72     // so we accept 'api_action' as an alias of action on getfields
  73     if (!empty($apiRequest['params']['api_action'])) {
  74       //  $apiRequest['params']['action'] = $apiRequest['params']['api_action'];
  75       // unset($apiRequest['params']['api_action']);
  76     }
  77     return ['action' => ['api.aliases' => ['api_action']]];
  78   }
  79   $getFieldsParams = ['action' => $apiRequest['action']];
  80   $entity = $apiRequest['entity'];
  81   if ($entity == 'Profile' && array_key_exists('profile_id', $apiRequest['params'])) {
  82     $getFieldsParams['profile_id'] = $apiRequest['params']['profile_id'];
  83   }
  84   $fields = civicrm_api3($entity, 'getfields', $getFieldsParams);
  85   return $fields['values'];
  86 }
  87
  88 /**
  89  * Check if the result is an error. Note that this function has been retained from
  90  * api v2 for convenience but the result is more standardised in v3 and param
  91  * 'format.is_success' => 1
  92  * will result in a boolean success /fail being returned if that is what you need.
  93  *
  94  * @param $result
  95  *
  96  * @return bool
  97  *   true if error, false otherwise
  98  */
  99 function civicrm_error($result) {
 100   if (is_array($result)) {
 101     return (array_key_exists('is_error', $result) &&
 102       $result['is_error']
 103     ) ? TRUE : FALSE;
 104   }
 105   return FALSE;
 106 }
 107
 108 /**
 109  * Get camel case version of entity name.
 110  *
 111  * @param string|null $entity
 112  *
 113  * @return string|null
 114  */
 115 function _civicrm_api_get_camel_name($entity) {
 116   return is_string($entity) ? CRM_Utils_String::convertStringToCamel($entity) : NULL;
 117 }
 118
 119 /**
 120  * Swap out any $values vars.
 121  *
 122  * Ie. the value after $value is swapped for the parent $result
 123  * 'activity_type_id' => '$value.testfield',
 124  * 'tag_id'  => '$value.api.tag.create.id',
 125  * 'tag1_id' => '$value.api.entity.create.0.id'
 126  *
 127  * @param array $params
 128  * @param array $parentResult
 129  * @param string $separator
 130  */
 131 function _civicrm_api_replace_variables(&$params, &$parentResult, $separator = '.') {
 132   foreach ($params as $field => &$value) {
 133     if (substr($field, 0, 4) == 'api.') {
 134       // CRM-21246 - Leave nested calls alone.
 135       continue;
 136     }
 137     if (is_string($value) && substr($value, 0, 6) == '$value') {
 138       $value = _civicrm_api_replace_variable($value, $parentResult, $separator);
 139     }
 140     // Handle the operator syntax: array('OP' => $val)
 141     elseif (is_array($value) && is_string(reset($value)) && substr(reset($value), 0, 6) == '$value') {
 142       $key = key($value);
 143       $value[$key] = _civicrm_api_replace_variable($value[$key], $parentResult, $separator);
 144       // A null value with an operator will cause an error, so remove it.
 145       if ($value[$key] === NULL) {
 146         $value = '';
 147       }
 148     }
 149   }
 150 }
 151
 152 /**
 153  * Swap out a $value.foo variable with the value from parent api results.
 154  *
 155  * Called by _civicrm_api_replace_variables to do the substitution.
 156  *
 157  * @param string $value
 158  * @param array $parentResult
 159  * @param string $separator
 160  * @return mixed|null
 161  */
 162 function _civicrm_api_replace_variable($value, $parentResult, $separator) {
 163   $valueSubstitute = substr($value, 7);
 164
 165   if (!empty($parentResult[$valueSubstitute])) {
 166     return $parentResult[$valueSubstitute];
 167   }
 168   else {
 169     $stringParts = explode($separator, $value);
 170     unset($stringParts[0]);
 171     // CRM-16168 If we have failed to swap it out we should unset it rather than leave the placeholder.
 172     $value = NULL;
 173
 174     $fieldname = array_shift($stringParts);
 175
 176     //when our string is an array we will treat it as an array from that . onwards
 177     $count = count($stringParts);
 178     while ($count > 0) {
 179       $fieldname .= "." . array_shift($stringParts);
 180       if (array_key_exists($fieldname, $parentResult) && is_array($parentResult[$fieldname])) {
 181         $arrayLocation = $parentResult[$fieldname];
 182         foreach ($stringParts as $key => $innerValue) {
 183           $arrayLocation = CRM_Utils_Array::value($innerValue, $arrayLocation);
 184         }
 185         $value = $arrayLocation;
 186       }
 187       $count = count($stringParts);
 188     }
 189   }
 190   return $value;
 191 }
 192
 193 /**
 194  * Convert possibly camel name to underscore separated entity name.
 195  *
 196  * @param string $entity
 197  *   Entity name in various formats e.g. Contribution, contribution,
 198  *   OptionValue, option_value, UFJoin, uf_join.
 199  *
 200  * @return string
 201  *   Entity name in underscore separated format.
 202  */
 203 function _civicrm_api_get_entity_name_from_camel($entity) {
 204   if (!$entity || $entity === strtolower($entity)) {
 205     return $entity;
 206   }
 207   elseif ($entity == 'PCP') {
 208     return 'pcp';
 209   }
 210   else {
 211     $entity = ltrim(strtolower(str_replace('U_F',
 212           'uf',
 213           // That's CamelCase, beside an odd UFCamel that is expected as uf_camel
 214           preg_replace('/(?=[A-Z])/', '_$0', $entity)
 215         )), '_');
 216   }
 217   return $entity;
 218 }
 219
 220 /**
 221  * Having a DAO object find the entity name.
 222  *
 223  * @param object $bao
 224  *   DAO being passed in.
 225  *
 226  * @return string
 227  */
 228 function _civicrm_api_get_entity_name_from_dao($bao) {
 229   $daoName = str_replace("BAO", "DAO", get_class($bao));
 230   return CRM_Core_DAO_AllCoreTables::getBriefName($daoName);
 231 }