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 }