api/api.php

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