api/api.php

   1 <?php
   2
   3 /**
   4  * @file
   5  * File for the CiviCRM APIv3 API wrapper.
   6  *
   7  * @package CiviCRM_APIv3
   8  * @subpackage API
   9  *
  10  * @copyright CiviCRM LLC (c) 2004-2014
  11  * @version $Id: api.php 30486 2010-11-02 16:12:09Z shot $
  12  */
  13
  14 /**
  15  * CiviCRM API wrapper function.
  16  *
  17  * @param string $entity
  18  *   type of entities to deal with
  19  * @param string $action
  20  *   create, get, delete or some special action name.
  21  * @param array $params
  22  *   array to be passed to function
  23  * @param null $extra
  24  *
  25  * @return array|int
  26  */
  27 function civicrm_api($entity, $action, $params, $extra = NULL) {
  28   return \Civi\Core\Container::singleton()->get('civi_api_kernel')->run($entity, $action, $params, $extra);
  29 }
  30
  31 /**
  32  * Version 3 wrapper for civicrm_api.
  33  *
  34  * Throws exception.
  35  *
  36  * @param string $entity
  37  *   Type of entities to deal with.
  38  * @param string $action
  39  *   Create, get, delete or some special action name.
  40  * @param array $params
  41  *   Array to be passed to function.
  42  *
  43  * @throws CiviCRM_API3_Exception
  44  * @return array
  45  */
  46 function civicrm_api3($entity, $action, $params = array()) {
  47   $params['version'] = 3;
  48   $result = civicrm_api($entity, $action, $params);
  49   if (is_array($result) && !empty($result['is_error'])) {
  50     throw new CiviCRM_API3_Exception($result['error_message'], CRM_Utils_Array::value('error_code', $result, 'undefined'), $result);
  51   }
  52   return $result;
  53 }
  54
  55 /**
  56  * Call getfields from api wrapper. This function ensures that settings that
  57  * could alter getfields output (e.g. action for all api & profile_id for
  58  * profile api ) are consistently passed in.
  59  *
  60  * We check whether the api call is 'getfields' because if getfields is
  61  * being called we return an empty array as no alias swapping, validation or
  62  * default filling is done on getfields & we want to avoid a loop
  63  *
  64  * @todo other output modifiers include contact_type
  65  *
  66  * @param array $apiRequest
  67  * @return array
  68  *   getfields output
  69  */
  70 function _civicrm_api3_api_getfields(&$apiRequest) {
  71   if (strtolower($apiRequest['action'] == 'getfields')) {
  72     // the main param getfields takes is 'action' - however this param is not compatible with REST
  73     // so we accept 'api_action' as an alias of action on getfields
  74     if (!empty($apiRequest['params']['api_action'])) {
  75       //  $apiRequest['params']['action'] = $apiRequest['params']['api_action'];
  76       // unset($apiRequest['params']['api_action']);
  77     }
  78     return array('action' => array('api.aliases' => array('api_action')));
  79   }
  80   $getFieldsParams = array('action' => $apiRequest['action']);
  81   $entity = $apiRequest['entity'];
  82   if ($entity == 'profile' && array_key_exists('profile_id', $apiRequest['params'])) {
  83     $getFieldsParams['profile_id'] = $apiRequest['params']['profile_id'];
  84   }
  85   $fields = civicrm_api3($entity, 'getfields', $getFieldsParams);
  86   return $fields['values'];
  87 }
  88
  89 /**
  90  * Check if the result is an error. Note that this function has been retained from
  91  * api v2 for convenience but the result is more standardised in v3 and param
  92  * 'format.is_success' => 1
  93  * will result in a boolean success /fail being returned if that is what you need.
  94  *
  95  * @param $result
  96  *
  97  * @return bool
  98  *   true if error, false otherwise
  99  */
 100 function civicrm_error($result) {
 101   if (is_array($result)) {
 102     return (array_key_exists('is_error', $result) &&
 103       $result['is_error']
 104     ) ? TRUE : FALSE;
 105   }
 106   return FALSE;
 107 }
 108
 109 /**
 110  * @param $entity
 111  *
 112  * @return string
 113  */
 114 function _civicrm_api_get_camel_name($entity) {
 115   return CRM_Utils_String::convertStringToCamel($entity);
 116 }
 117
 118 /**
 119  * Swap out any $values vars - ie. the value after $value is swapped for the parent $result
 120  * 'activity_type_id' => '$value.testfield',
 121  * 'tag_id'  => '$value.api.tag.create.id',
 122  * 'tag1_id' => '$value.api.entity.create.0.id'
 123  *
 124  * @param array $params
 125  * @param array $parentResult
 126  * @param string $separator
 127  */
 128 function _civicrm_api_replace_variables(&$params, &$parentResult, $separator = '.') {
 129
 130   foreach ($params as $field => $value) {
 131
 132     if (is_string($value) && substr($value, 0, 6) == '$value') {
 133       $valueSubstitute = substr($value, 7);
 134
 135       if (!empty($parentResult[$valueSubstitute])) {
 136         $params[$field] = $parentResult[$valueSubstitute];
 137       }
 138       else {
 139
 140         $stringParts = explode($separator, $value);
 141         unset($stringParts[0]);
 142
 143         $fieldname = array_shift($stringParts);
 144
 145         //when our string is an array we will treat it as an array from that . onwards
 146         $count = count($stringParts);
 147         while ($count > 0) {
 148           $fieldname .= "." . array_shift($stringParts);
 149           if (array_key_exists($fieldname, $parentResult) && is_array($parentResult[$fieldname])) {
 150             $arrayLocation = $parentResult[$fieldname];
 151             foreach ($stringParts as $key => $innerValue) {
 152               $arrayLocation = CRM_Utils_Array::value($innerValue, $arrayLocation);
 153             }
 154             $params[$field] = $arrayLocation;
 155           }
 156           $count = count($stringParts);
 157         }
 158       }
 159     }
 160   }
 161 }
 162
 163 /**
 164  * Convert possibly camel name to underscore separated entity name
 165  *
 166  * @param string $entity
 167  *   Entity name in various formats e.g. Contribution, contribution,
 168  *   OptionValue, option_value, UFJoin, uf_join.
 169  * @return string
 170  *   Entity name in underscore separated format.
 171  *
 172  * @fixme Why isn't this called first thing in civicrm_api wrapper?
 173  */
 174 function _civicrm_api_get_entity_name_from_camel($entity) {
 175   if ($entity == strtolower($entity)) {
 176     return $entity;
 177   }
 178   else {
 179     $entity = ltrim(strtolower(str_replace('U_F',
 180           'uf',
 181           // That's CamelCase, beside an odd UFCamel that is expected as uf_camel
 182           preg_replace('/(?=[A-Z])/', '_$0', $entity)
 183         )), '_');
 184   }
 185   return $entity;
 186 }
 187
 188 /**
 189  * Having a DAO object find the entity name
 190  * @param object $bao
 191  *   DAO being passed in.
 192  * @return string
 193  */
 194 function _civicrm_api_get_entity_name_from_dao($bao) {
 195   $daoName = str_replace("BAO", "DAO", get_class($bao));
 196   return _civicrm_api_get_entity_name_from_camel(CRM_Core_DAO_AllCoreTables::getBriefName($daoName));
 197 }