api/v3/utils.php

   1 <?php
   2 // $Id$
   3
   4 /*
   5   +--------------------------------------------------------------------+
   6   | CiviCRM version 4.3                                                |
   7   +--------------------------------------------------------------------+
   8   | Copyright CiviCRM LLC (c) 2004-2013                                |
   9   +--------------------------------------------------------------------+
  10   | This file is a part of CiviCRM.                                    |
  11   |                                                                    |
  12   | CiviCRM is free software; you can copy, modify, and distribute it  |
  13   | under the terms of the GNU Affero General Public License           |
  14   | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  15   |                                                                    |
  16   | CiviCRM is distributed in the hope that it will be useful, but     |
  17   | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  18   | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  19   | See the GNU Affero General Public License for more details.        |
  20   |                                                                    |
  21   | You should have received a copy of the GNU Affero General Public   |
  22   | License and the CiviCRM Licensing Exception along                  |
  23   | with this program; if not, contact CiviCRM LLC                     |
  24   | at info[AT]civicrm[DOT]org. If you have questions about the        |
  25   | GNU Affero General Public License or the licensing of CiviCRM,     |
  26   | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  27   +--------------------------------------------------------------------+
  28 */
  29
  30 /**
  31  * File for CiviCRM APIv3 utilitity functions
  32  *
  33  * @package CiviCRM_APIv3
  34  * @subpackage API_utils
  35  *
  36  * @copyright CiviCRM LLC (c) 2004-2013
  37  * @version $Id: utils.php 30879 2010-11-22 15:45:55Z shot $
  38  *
  39  */
  40
  41 /**
  42  * Initialize CiviCRM - should be run at the start of each API function
  43  */
  44 function _civicrm_api3_initialize() {
  45   require_once 'CRM/Core/Config.php';
  46   $config = CRM_Core_Config::singleton();
  47   }
  48
  49 /*
  50  * Wrapper Function for civicrm_verify_mandatory to make it simple to pass either / or fields for checking
  51  *
  52  * @param array $params array of fields to check
  53  * @param array $daoName string DAO to check for required fields (create functions only)
  54  * @param array $keys list of required fields options. One of the options is required
  55  * @return null or throws error if there the required fields not present
  56
  57  * @
  58  *
  59  */
  60 function civicrm_api3_verify_one_mandatory($params, $daoName = NULL, $keyoptions = array(
  61   )) {
  62   $keys = array(array());
  63   foreach ($keyoptions as $key) {
  64     $keys[0][] = $key;
  65   }
  66   civicrm_api3_verify_mandatory($params, $daoName, $keys);
  67 }
  68
  69 /*
  70  * Function to check mandatory fields are included
  71  *
  72  * @param array $params array of fields to check
  73  * @param array $daoName string DAO to check for required fields (create functions only)
  74  * @param array $keys list of required fields. A value can be an array denoting that either this or that is required.
  75  * @param bool $verifyDAO
  76  *
  77  * @return null or throws error if there the required fields not present
  78  *
  79  * @todo see notes on _civicrm_api3_check_required_fields regarding removing $daoName param
  80  */
  81 function civicrm_api3_verify_mandatory($params, $daoName = NULL, $keys = array(
  82   ), $verifyDAO = TRUE) {
  83
  84   $unmatched = array();
  85   if ($daoName != NULL && $verifyDAO && empty($params['id'])) {
  86     $unmatched = _civicrm_api3_check_required_fields($params, $daoName, TRUE);
  87     if (!is_array($unmatched)) {
  88       $unmatched = array();
  89     }
  90   }
  91
  92   if (!empty($params['id'])) {
  93     $keys = array('version');
  94   }
  95   else {
  96     if (!in_array('version', $keys)) {
  97       // required from v3 onwards
  98       $keys[] = 'version';
  99     }
 100   }
 101   foreach ($keys as $key) {
 102     if (is_array($key)) {
 103       $match = 0;
 104       $optionset = array();
 105       foreach ($key as $subkey) {
 106         if (!array_key_exists($subkey, $params) || empty($params[$subkey])) {
 107           $optionset[] = $subkey;
 108         }
 109         else {
 110           // as long as there is one match then we don't need to rtn anything
 111           $match = 1;
 112         }
 113       }
 114       if (empty($match) && !empty($optionset)) {
 115         $unmatched[] = "one of (" . implode(", ", $optionset) . ")";
 116       }
 117     }
 118     else {
 119       if (!array_key_exists($key, $params) || empty($params[$key])) {
 120         $unmatched[] = $key;
 121       }
 122     }
 123   }
 124   if (!empty($unmatched)) {
 125     throw new API_Exception("Mandatory key(s) missing from params array: " . implode(", ", $unmatched),"mandatory_missing",array("fields"=>$unmatched));
 126   }
 127 }
 128
 129 /**
 130  *
 131  * @param <type> $msg
 132  * @param <type> $data
 133  * @param object $dao DAO / BAO object to be freed here
 134  *
 135  * @return <type>
 136  */
 137 function civicrm_api3_create_error($msg, $data = array(
 138   ), &$dao = NULL) {
 139   //fix me - $dao should be param 4 & 3 should be $apiRequest
 140   if (is_object($dao)) {
 141     $dao->free();
 142   }
 143
 144   if (is_array($dao)) {
 145     if ($msg == 'DB Error: constraint violation' || substr($msg, 0,9)  == 'DB Error:' || $msg == 'DB Error: already exists') {
 146       try {
 147         _civicrm_api3_validate_fields($dao['entity'], $dao['action'], $dao['params'], True);
 148       }
 149       catch(Exception $e) {
 150         $msg = $e->getMessage();
 151       }
 152     }
 153   }
 154   $data['is_error'] = 1;
 155   $data['error_message'] = $msg;
 156   if (is_array($dao) && isset($dao['params']) && is_array($dao['params']) && CRM_Utils_Array::value('api.has_parent', $dao['params'])) {
 157     $errorCode = empty($data['error_code']) ? 'chained_api_failed' : $data['error_code'];
 158     throw new API_Exception('Error in call to ' . $dao['entity'] . '_' . $dao['action'] . ' : ' . $msg, $errorCode, $data);
 159   }
 160   return $data;
 161 }
 162
 163 /**
 164  * Format array in result output styple
 165  *
 166  * @param array $values values generated by API operation (the result)
 167  * @param array $params parameters passed into API call
 168  * @param string $entity the entity being acted on
 169  * @param string $action the action passed to the API
 170  * @param object $dao DAO object to be freed here
 171  * @param array $extraReturnValues additional values to be added to top level of result array(
 172  *   - this param is currently used for legacy behaviour support
 173  *
 174  * @return array $result
 175  */
 176 function civicrm_api3_create_success($values = 1, $params = array(
 177   ), $entity = NULL, $action = NULL, &$dao = NULL, $extraReturnValues = array()) {
 178   $result = array();
 179   $result['is_error'] = 0;
 180   //lets set the ['id'] field if it's not set & we know what the entity is
 181   if (is_array($values) && !empty($entity)) {
 182     foreach ($values as $key => $item) {
 183       if (empty($item['id']) && !empty($item[$entity . "_id"])) {
 184         $values[$key]['id'] = $item[$entity . "_id"];
 185       }
 186     }
 187   }
 188   //if ( array_key_exists ('debug',$params) && is_object ($dao)) {
 189   if (is_array($params) && array_key_exists('debug', $params)) {
 190     if (!is_object($dao)) {
 191       $d = _civicrm_api3_get_DAO(CRM_Utils_Array::value('entity', $params));
 192       if (!empty($d)) {
 193         $file = str_replace('_', '/', $d) . ".php";
 194         require_once ($file);
 195         $dao = new $d();
 196       }
 197     }
 198     if (is_string($action) && $action != 'getfields') {
 199       $apiFields = civicrm_api($entity, 'getfields', array('version' => 3, 'action' => $action) + $params);
 200     }
 201     elseif ($action != 'getfields') {
 202       $apiFields = civicrm_api($entity, 'getfields', array('version' => 3) + $params);
 203     }
 204     else {
 205       $apiFields = FALSE;
 206     }
 207
 208     $allFields = array();
 209     if ($action != 'getfields' && is_array($apiFields) && is_array(CRM_Utils_Array::value('values', $apiFields))) {
 210       $allFields = array_keys($apiFields['values']);
 211     }
 212     $paramFields = array_keys($params);
 213     $undefined = array_diff($paramFields, $allFields, array_keys($_COOKIE), array('action', 'entity', 'debug', 'version', 'check_permissions', 'IDS_request_uri', 'IDS_user_agent', 'return', 'sequential', 'rowCount', 'option_offset', 'option_limit', 'custom', 'option_sort'));
 214     if ($undefined) {
 215       $result['undefined_fields'] = array_merge($undefined);
 216     }
 217   }
 218   if (is_object($dao)) {
 219     $dao->free();
 220   }
 221
 222   $result['version'] = 3;
 223   if (is_array($values)) {
 224     $result['count'] = count($values);
 225
 226     // Convert value-separated strings to array
 227     _civicrm_api3_separate_values($values);
 228
 229     if ($result['count'] == 1) {
 230       list($result['id']) = array_keys($values);
 231     }
 232     elseif (!empty($values['id']) && is_int($values['id'])) {
 233       $result['id'] = $values['id'];
 234     }
 235   }
 236   else {
 237     $result['count'] = !empty($values) ? 1 : 0;
 238   }
 239
 240   if (is_array($values) && isset($params['sequential']) &&
 241     $params['sequential'] == 1
 242   ) {
 243     $result['values'] = array_values($values);
 244   }
 245   else {
 246     $result['values'] = $values;
 247   }
 248
 249   return array_merge($result, $extraReturnValues);
 250 }
 251 /*
 252  * Load the DAO of the entity
 253  */
 254 function _civicrm_api3_load_DAO($entity) {
 255   $dao = _civicrm_api3_get_DAO($entity);
 256   if (empty($dao)) {
 257     return FALSE;
 258   }
 259   $file = str_replace('_', '/', $dao) . ".php";
 260   require_once ($file);
 261   $d = new $dao();
 262   return $d;
 263 }
 264 /*
 265  * Function to return the DAO of the function or Entity
 266  * @param  $name is either a function of the api (civicrm_{entity}_create or the entity name
 267  * return the DAO name to manipulate this function
 268  * eg. "civicrm_api3_contact_create" or "Contact" will return "CRM_Contact_BAO_Contact"
 269  */
 270 function _civicrm_api3_get_DAO($name) {
 271   static $dao = NULL;
 272   if (!$dao) {
 273     require ('CRM/Core/DAO/.listAll.php');
 274   }
 275
 276   if (strpos($name, 'civicrm_api3') !== FALSE) {
 277     $last = strrpos($name, '_');
 278     // len ('civicrm_api3_') == 13
 279     $name = substr($name, 13, $last - 13);
 280   }
 281
 282   if (strtolower($name) == 'individual' || strtolower($name) == 'household' || strtolower($name) == 'organization') {
 283     $name = 'Contact';
 284   }
 285
 286   //hack to deal with incorrectly named BAO/DAO - see CRM-10859 - remove after rename
 287   if($name == 'price_set'){
 288     return 'CRM_Price_DAO_Set';
 289   }
 290   if($name == 'price_field'){
 291     return 'CRM_Price_DAO_Field';
 292   }
 293   if($name == 'price_field_value'){
 294     return 'CRM_Price_DAO_FieldValue';
 295   }
 296   // these aren't listed on ticket CRM-10859 - but same problem - lack of standardisation
 297   if($name == 'mailing_job' || $name == 'MailingJob'){
 298     return 'CRM_Mailing_BAO_Job';
 299   }
 300   if($name == 'mailing_recipients' || $name == 'MailingRecipients'){
 301     return 'CRM_Mailing_BAO_Recipients';
 302   }
 303   if(strtolower($name) == 'im'){
 304     return 'CRM_Core_BAO_IM';
 305   }
 306
 307
 308   return CRM_Utils_Array::value(_civicrm_api_get_camel_name($name, 3), $dao);
 309 }
 310
 311 /*
 312  * Function to return the DAO of the function or Entity
 313  * @param  $name is either a function of the api (civicrm_{entity}_create or the entity name
 314  * return the DAO name to manipulate this function
 315  * eg. "civicrm_contact_create" or "Contact" will return "CRM_Contact_BAO_Contact"
 316  */
 317 function _civicrm_api3_get_BAO($name) {
 318   $dao = _civicrm_api3_get_DAO($name);
 319   $dao = str_replace("DAO", "BAO", $dao);
 320   return $dao;
 321 }
 322
 323 /**
 324  *  Recursive function to explode value-separated strings into arrays
 325  *
 326  */
 327 function _civicrm_api3_separate_values(&$values) {
 328   $sp = CRM_Core_DAO::VALUE_SEPARATOR;
 329   foreach ($values as $key => & $value) {
 330     if (is_array($value)) {
 331       _civicrm_api3_separate_values($value);
 332     }
 333     elseif (is_string($value)) {
 334       if($key == 'case_type_id'){// this is to honor the way case API was originally written
 335         $value = trim(str_replace($sp, ',', $value), ',');
 336       }
 337       elseif (strpos($value, $sp) !== FALSE) {
 338         $value = explode($sp, trim($value, $sp));
 339       }
 340     }
 341   }
 342 }
 343 /*
 344  * This is a wrapper for api_store_values which will check the suitable fields using getfields
 345  * rather than DAO->fields
 346  *
 347  * Getfields has handling for how to deal with uniquenames which dao->fields doesn't
 348  *
 349  * Note this is used by BAO type create functions - eg. contribution
 350  * @param string $entity
 351  * @param array $params
 352  * @param array $values
 353  */
 354 function _civicrm_api3_filter_fields_for_bao($entity, &$params, &$values){
 355   $fields = civicrm_api($entity,'getfields', array('version' => 3,'action' => 'create'));
 356   $fields = $fields['values'];
 357   _civicrm_api3_store_values($fields, $params, $values);
 358 }
 359 /**
 360  *
 361  * @param array $fields
 362  * @param array $params
 363  * @param array $values
 364  *
 365  * @return Bool $valueFound
 366  */
 367 function _civicrm_api3_store_values(&$fields, &$params, &$values) {
 368   $valueFound = FALSE;
 369
 370   $keys = array_intersect_key($params, $fields);
 371   foreach ($keys as $name => $value) {
 372     if ($name !== 'id') {
 373       $values[$name] = $value;
 374       $valueFound = TRUE;
 375     }
 376   }
 377   return $valueFound;
 378 }
 379 /**
 380  * The API supports 2 types of get requestion. The more complex uses the BAO query object.
 381  *  This is a generic function for those functions that call it
 382  *
 383  *  At the moment only called by contact we should extend to contribution &
 384  *  others that use the query object. Note that this function passes permission information in.
 385  *  The others don't
 386  *
 387  * @param array $params as passed into api get or getcount function
 388  * @param array $options array of options (so we can modify the filter)
 389  * @param bool $getCount are we just after the count
 390  */
 391 function _civicrm_api3_get_using_query_object($entity, $params, $additional_options = array(), $getCount = null){
 392
 393   // Convert id to e.g. contact_id
 394   if (empty($params[$entity . '_id']) && isset($params['id'])) {
 395     $params[$entity . '_id'] = $params['id'];
 396   }
 397   unset($params['id']);
 398
 399   $options = _civicrm_api3_get_options_from_params($params, TRUE);
 400
 401   $inputParams = array_merge(
 402     CRM_Utils_Array::value('input_params', $options, array()),
 403     CRM_Utils_Array::value('input_params', $additional_options, array())
 404   );
 405   $returnProperties = array_merge(
 406     CRM_Utils_Array::value('return', $options, array()),
 407     CRM_Utils_Array::value('return', $additional_options, array())
 408   );
 409   if(empty($returnProperties)){
 410     $returnProperties = null;
 411   }
 412   if(!empty($params['check_permissions'])){
 413     // we will filter query object against getfields
 414     $fields = civicrm_api($entity, 'getfields', array('version' => 3, 'action' => 'get'));
 415     // we need to add this in as earlier in this function 'id' was unset in favour of $entity_id
 416     $fields['values'][$entity . '_id'] = array();
 417     $varsToFilter = array('returnProperties', 'inputParams');
 418     foreach ($varsToFilter as $varToFilter){
 419       if(!is_array($$varToFilter)){
 420         continue;
 421       }
 422       //I was going to throw an exception rather than silently filter out - but
 423       //would need to diff out of exceptions arr other keys like 'options', 'return', 'api. etcetc
 424       //so we are silently ignoring parts of their request
 425       //$exceptionsArr = array_diff(array_keys($$varToFilter), array_keys($fields['values']));
 426       $$varToFilter = array_intersect_key($$varToFilter, $fields['values']);
 427     }
 428   }
 429   $options = array_merge($options,$additional_options);
 430   $sort             = CRM_Utils_Array::value('sort', $options, NULL);
 431   $offset             = CRM_Utils_Array::value('offset', $options, NULL);
 432   $limit             = CRM_Utils_Array::value('limit', $options, NULL);
 433   $smartGroupCache  = CRM_Utils_Array::value('smartGroupCache', $params);
 434
 435   if($getCount){
 436     $limit = NULL;
 437     $returnProperties = NULL;
 438   }
 439
 440   $newParams = CRM_Contact_BAO_Query::convertFormValues($inputParams);
 441   $skipPermissions = CRM_Utils_Array::value('check_permissions', $params)? 0 :1;
 442   list($entities, $options) = CRM_Contact_BAO_Query::apiQuery(
 443     $newParams,
 444     $returnProperties,
 445     NULL,
 446     $sort,
 447     $offset ,
 448     $limit,
 449     $smartGroupCache,
 450     $getCount,
 451     $skipPermissions
 452   );
 453   if ($getCount) { // only return the count of contacts
 454     return $entities;
 455   }
 456
 457   return $entities;
 458 }
 459 /*
 460  * Function transfers the filters being passed into the DAO onto the params object
 461  */
 462 function _civicrm_api3_dao_set_filter(&$dao, $params, $unique = TRUE, $entity) {
 463   $entity = substr($dao->__table, 8);
 464
 465   $allfields = _civicrm_api3_build_fields_array($dao, $unique);
 466
 467   $fields = array_intersect(array_keys($allfields), array_keys($params));
 468   if (isset($params[$entity . "_id"])) {
 469     //if entity_id is set then treat it as ID (will be overridden by id if set)
 470     $dao->id = $params[$entity . "_id"];
 471   }
 472   //apply options like sort
 473   _civicrm_api3_apply_options_to_dao($params, $dao, $entity);
 474
 475   //accept filters like filter.activity_date_time_high
 476   // std is now 'filters' => ..
 477   if (strstr(implode(',', array_keys($params)), 'filter')) {
 478     if (isset($params['filters']) && is_array($params['filters'])) {
 479       foreach ($params['filters'] as $paramkey => $paramvalue) {
 480         _civicrm_api3_apply_filters_to_dao($paramkey, $paramvalue, $dao);
 481       }
 482     }
 483     else {
 484       foreach ($params as $paramkey => $paramvalue) {
 485         if (strstr($paramkey, 'filter')) {
 486           _civicrm_api3_apply_filters_to_dao(substr($paramkey, 7), $paramvalue, $dao);
 487         }
 488       }
 489     }
 490   }
 491   // http://issues.civicrm.org/jira/browse/CRM-9150 - stick with 'simple' operators for now
 492   // support for other syntaxes is discussed in ticket but being put off for now
 493   $acceptedSQLOperators = array('=', '<=', '>=', '>', '<', 'LIKE', "<>", "!=", "NOT LIKE", 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN');
 494   if (!$fields) {
 495     $fields = array();
 496   }
 497
 498   foreach ($fields as $field) {
 499     if (is_array($params[$field])) {
 500       //get the actual fieldname from db
 501       $fieldName = $allfields[$field]['name'];
 502       //array is the syntax for SQL clause
 503       foreach ($params[$field] as $operator => $criteria) {
 504         if (in_array($operator, $acceptedSQLOperators)) {
 505           switch ($operator) {
 506             // unary operators
 507
 508             case 'IS NULL':
 509             case 'IS NOT NULL':
 510               $dao->whereAdd(sprintf('%s %s', $fieldName, $operator));
 511               break;
 512
 513             // ternary operators
 514
 515             case 'BETWEEN':
 516             case 'NOT BETWEEN':
 517               if (empty($criteria[0]) || empty($criteria[1])) {
 518                 throw new exception("invalid criteria for $operator");
 519               }
 520               $dao->whereAdd(sprintf('%s ' . $operator . ' "%s" AND "%s"', $fieldName, CRM_Core_DAO::escapeString($criteria[0]), CRM_Core_DAO::escapeString($criteria[1])));
 521               break;
 522
 523             // n-ary operators
 524
 525             case 'IN':
 526             case 'NOT IN':
 527               if (empty($criteria)) {
 528                 throw new exception("invalid criteria for $operator");
 529               }
 530               $escapedCriteria = array_map(array('CRM_Core_DAO', 'escapeString'), $criteria);
 531               $dao->whereAdd(sprintf('%s %s ("%s")', $fieldName, $operator, implode('", "', $escapedCriteria)));
 532               break;
 533
 534             // binary operators
 535
 536             default:
 537
 538               $dao->whereAdd(sprintf('%s %s "%s"', $fieldName, $operator, CRM_Core_DAO::escapeString($criteria)));
 539           }
 540         }
 541       }
 542     }
 543     else {
 544       if ($unique) {
 545         $dao->$allfields[$field]['name'] = $params[$field];
 546       }
 547       else {
 548         $dao->$field = $params[$field];
 549       }
 550     }
 551   }
 552   if (!empty($params['return']) && is_array($params['return'])) {
 553     $dao->selectAdd();
 554     $allfields =  _civicrm_api3_get_unique_name_array($dao);
 555     $returnMatched = array_intersect($params['return'], $allfields);
 556     $returnUniqueMatched = array_intersect(
 557       array_diff(// not already matched on the field names
 558         $params['return'],
 559         $returnMatched),
 560         array_flip($allfields)// but a match for the field keys
 561     );
 562
 563     foreach ($returnMatched as $returnValue) {
 564         $dao->selectAdd($returnValue);
 565     }
 566     foreach ($returnUniqueMatched as $uniqueVal){
 567       $dao->selectAdd($allfields[$uniqueVal]);
 568
 569     }
 570     $dao->selectAdd('id');
 571   }
 572 }
 573
 574 /*
 575  * Apply filters (e.g. high, low) to DAO object (prior to find)
 576  * @param string $filterField field name of filter
 577  * @param string $filterValue field value of filter
 578  * @param object $dao DAO object
 579  */
 580 function _civicrm_api3_apply_filters_to_dao($filterField, $filterValue, &$dao) {
 581   if (strstr($filterField, 'high')) {
 582     $fieldName = substr($filterField, 0, -5);
 583     $dao->whereAdd("($fieldName <= $filterValue )");
 584   }
 585   if (strstr($filterField, 'low')) {
 586     $fieldName = substr($filterField, 0, -4);
 587     $dao->whereAdd("($fieldName >= $filterValue )");
 588   }
 589   if($filterField == 'is_current' && $filterValue == 1){
 590     $todayStart = date('Ymd000000', strtotime('now'));
 591     $todayEnd = date('Ymd235959', strtotime('now'));
 592     $dao->whereAdd("(start_date <= '$todayStart' OR start_date IS NULL) AND (end_date >= '$todayEnd' OR end_date IS NULL)");
 593     if(property_exists($dao, 'is_active')){
 594       $dao->whereAdd('is_active = 1');
 595     }
 596   }
 597 }
 598 /*
 599  *
 600  * Get sort, limit etc options from the params - supporting old & new formats.
 601  * get returnproperties for legacy
 602  * @param array $params params array as passed into civicrm_api
 603  * @param bool $queryObject - is this supporting a queryobject api (e.g contact) - if so we support more options
 604  * for legacy report & return a unique fields array
 605  * @return array $options options extracted from params
 606  */
 607 function _civicrm_api3_get_options_from_params(&$params, $queryObject = false, $entity = '', $action = '') {
 608   $sort = CRM_Utils_Array::value('sort', $params, 0);
 609   $sort = CRM_Utils_Array::value('option.sort', $params, $sort);
 610   $sort = CRM_Utils_Array::value('option_sort', $params, $sort);
 611
 612   $offset = CRM_Utils_Array::value('offset', $params, 0);
 613   $offset = CRM_Utils_Array::value('option.offset', $params, $offset);
 614   // dear PHP thought it would be a good idea to transform a.b into a_b in the get/post
 615   $offset = CRM_Utils_Array::value('option_offset', $params, $offset);
 616
 617   $limit = CRM_Utils_Array::value('rowCount', $params, 25);
 618   $limit = CRM_Utils_Array::value('option.limit', $params, $limit);
 619   $limit = CRM_Utils_Array::value('option_limit', $params, $limit);
 620
 621   if (is_array(CRM_Utils_Array::value('options', $params))) {
 622     $offset = CRM_Utils_Array::value('offset', $params['options'], $offset);
 623     $limit  = CRM_Utils_Array::value('limit', $params['options'], $limit);
 624     $sort   = CRM_Utils_Array::value('sort', $params['options'], $sort);
 625   }
 626
 627   $returnProperties = array();
 628   // handle the format return =sort_name,display_name...
 629   if (array_key_exists('return', $params)) {
 630     if (is_array($params['return'])) {
 631       $returnProperties = array_fill_keys($params['return'], 1);
 632     }
 633     else {
 634       $returnProperties = explode(',', str_replace(' ', '', $params['return']));
 635       $returnProperties = array_fill_keys($returnProperties, 1);
 636     }
 637   }
 638   if($entity && $action =='get' ){
 639     if(CRM_Utils_Array::value('id',$returnProperties)){
 640       $returnProperties[$entity . '_id'] = 1;
 641       unset($returnProperties['id']);
 642     }
 643     switch (trim(strtolower($sort))){
 644     case 'id':
 645     case 'id desc':
 646     case 'id asc':
 647       $sort = str_replace('id', $entity . '_id',$sort);
 648     }
 649   }
 650
 651
 652   $options = array(
 653     'offset' => $offset,
 654     'sort' => $sort,
 655     'limit' => $limit,
 656     'return' => !empty($returnProperties) ? $returnProperties : NULL,
 657   );
 658   if (!$queryObject) {
 659     return $options;
 660   }
 661   //here comes the legacy support for $returnProperties, $inputParams e.g for contat_get
 662   // if the queryobject is being used this should be used
 663   $inputParams = array();
 664   $legacyreturnProperties = array();
 665   $otherVars = array(
 666     'sort', 'offset', 'rowCount', 'options','return',
 667   );
 668   foreach ($params as $n => $v) {
 669     if (substr($n, 0, 7) == 'return.') {
 670       $legacyreturnProperties[substr($n, 7)] = $v;
 671     }
 672     elseif($n == 'id'){
 673       $inputParams[$entity. '_id'] = $v;
 674     }
 675     elseif (in_array($n, $otherVars)) {}
 676     else{
 677       $inputParams[$n] = $v;
 678     }
 679   }
 680   $options['return'] = array_merge($returnProperties, $legacyreturnProperties);
 681   $options['input_params'] = $inputParams;
 682   return $options;
 683 }
 684 /*
 685  * Apply options (e.g. sort, limit, order by) to DAO object (prior to find)
 686  * @param array $params params array as passed into civicrm_api
 687  * @param object $dao DAO object
 688  */
 689 function _civicrm_api3_apply_options_to_dao(&$params, &$dao, $entity) {
 690
 691   $options = _civicrm_api3_get_options_from_params($params,false,$entity);
 692   $dao->limit((int)$options['offset'], (int)$options['limit']);
 693   if (!empty($options['sort'])) {
 694     $dao->orderBy($options['sort']);
 695   }
 696 }
 697
 698
 699 /*
 700  * build fields array. This is the array of fields as it relates to the given DAO
 701  * returns unique fields as keys by default but if set but can return by DB fields
 702  */
 703 function _civicrm_api3_build_fields_array(&$bao, $unique = TRUE) {
 704   $fields = $bao->fields();
 705   if ($unique) {
 706     if(!CRM_Utils_Array::value('id', $fields)){
 707      $entity = _civicrm_api_get_entity_name_from_dao($bao);
 708      $fields['id'] = $fields[$entity . '_id'];
 709      unset($fields[$entity . '_id']);
 710     }
 711     return $fields;
 712   }
 713
 714   foreach ($fields as $field) {
 715     $dbFields[$field['name']] = $field;
 716   }
 717   return $dbFields;
 718 }
 719
 720 /*
 721  * build fields array. This is the array of fields as it relates to the given DAO
 722  * returns unique fields as keys by default but if set but can return by DB fields
 723  */
 724 function _civicrm_api3_get_unique_name_array(&$bao) {
 725   $fields = $bao->fields();
 726   foreach ($fields as $field => $values) {
 727     $uniqueFields[$field] = CRM_Utils_Array::value('name',$values, $field);
 728   }
 729   return $uniqueFields;
 730 }
 731
 732
 733 /**
 734  * Converts an DAO object to an array
 735  *
 736  * @param  object   $dao           (reference )object to convert
 737  * @params array of arrays (key = id) of array of fields
 738  * @static void
 739  * @access public
 740  */
 741 function _civicrm_api3_dao_to_array($dao, $params = NULL, $uniqueFields = TRUE, $entity = "") {
 742   $result = array();
 743   if (empty($dao) || !$dao->find()) {
 744     return array();
 745   }
 746
 747   //if custom fields are required we will endeavour to set them . NB passing $entity in might be a bit clunky / unrequired
 748   if (!empty($entity) && CRM_Utils_Array::value('return', $params) && is_array($params['return'])) {
 749     foreach ($params['return'] as $return) {
 750       if (substr($return, 0, 6) == 'custom') {
 751         $custom = TRUE;
 752       }
 753     }
 754   }
 755
 756
 757   $fields = array_keys(_civicrm_api3_build_fields_array($dao, $uniqueFields));
 758
 759   while ($dao->fetch()) {
 760     $tmp = array();
 761     foreach ($fields as $key) {
 762       if (array_key_exists($key, $dao)) {
 763         // not sure on that one
 764         if ($dao->$key !== NULL) {
 765           $tmp[$key] = $dao->$key;
 766         }
 767       }
 768     }
 769     $result[$dao->id] = $tmp;
 770     if (!empty($custom)) {
 771       _civicrm_api3_custom_data_get($result[$dao->id], $entity, $dao->id);
 772     }
 773   }
 774
 775
 776   return $result;
 777 }
 778
 779 /**
 780  * Converts an object to an array
 781  *
 782  * @param  object   $dao           (reference) object to convert
 783  * @param  array    $values        (reference) array
 784  * @param  array    $uniqueFields
 785  *
 786  * @return array
 787  * @static void
 788  * @access public
 789  */
 790 function _civicrm_api3_object_to_array(&$dao, &$values, $uniqueFields = FALSE) {
 791
 792   $fields = _civicrm_api3_build_fields_array($dao, $uniqueFields);
 793   foreach ($fields as $key => $value) {
 794     if (array_key_exists($key, $dao)) {
 795       $values[$key] = $dao->$key;
 796     }
 797   }
 798 }
 799
 800 /*
 801  * Wrapper for _civicrm_object_to_array when api supports unique fields
 802  */
 803 function _civicrm_api3_object_to_array_unique_fields(&$dao, &$values) {
 804   return _civicrm_api3_object_to_array($dao, $values, TRUE);
 805 }
 806
 807 /**
 808  *
 809  * @param array $params
 810  * @param array $values
 811  * @param string $extends entity that this custom field extends (e.g. contribution, event, contact)
 812  * @param string $entityId ID of entity per $extends
 813  */
 814 function _civicrm_api3_custom_format_params($params, &$values, $extends, $entityId = NULL) {
 815   $values['custom'] = array();
 816   foreach ($params as $key => $value) {
 817     list($customFieldID, $customValueID) = CRM_Core_BAO_CustomField::getKeyID($key, TRUE);
 818     if ($customFieldID) {
 819       CRM_Core_BAO_CustomField::formatCustomField($customFieldID, $values['custom'],
 820         $value, $extends, $customValueID, $entityId, FALSE, FALSE
 821       );
 822     }
 823   }
 824 }
 825
 826 /**
 827  * @deprecated
 828  * This function ensures that we have the right input parameters
 829  *
 830  * This function is only called when $dao is passed into verify_mandatory.
 831  * The practice of passing $dao into verify_mandatory turned out to be
 832  * unsatisfactory as the required fields @ the dao level is so diffent to the abstract
 833  * api level. Hence the intention is to remove this function
 834  * & the associated param from viery_mandatory
 835  *
 836  * @param array  $params       Associative array of property name/value
 837  *                             pairs to insert in new history.
 838  * @daoName string DAO to check params agains
 839  *
 840  * @return bool should the missing fields be returned as an array (core error created as default)
 841  *
 842  * @return bool true if all fields present, depending on $result a core error is created of an array of missing fields is returned
 843  * @access public
 844  */
 845 function _civicrm_api3_check_required_fields($params, $daoName, $return = FALSE) {
 846   //@deprecated - see notes
 847   if (isset($params['extends'])) {
 848     if (($params['extends'] == 'Activity' ||
 849         $params['extends'] == 'Phonecall' ||
 850         $params['extends'] == 'Meeting' ||
 851         $params['extends'] == 'Group' ||
 852         $params['extends'] == 'Contribution'
 853       ) &&
 854       ($params['style'] == 'Tab')
 855     ) {
 856       return civicrm_api3_create_error(ts("Can not create Custom Group in Tab for " . $params['extends']));
 857     }
 858   }
 859
 860   $dao = new $daoName();
 861   $fields = $dao->fields();
 862
 863   $missing = array();
 864   foreach ($fields as $k => $v) {
 865     if ($v['name'] == 'id') {
 866       continue;
 867     }
 868
 869     if (CRM_Utils_Array::value('required', $v)) {
 870       // 0 is a valid input for numbers, CRM-8122
 871       if (!isset($params[$k]) || (empty($params[$k]) && !($params[$k] === 0))) {
 872         $missing[] = $k;
 873       }
 874     }
 875   }
 876
 877   if (!empty($missing)) {
 878     if (!empty($return)) {
 879       return $missing;
 880     }
 881     else {
 882       return civicrm_api3_create_error(ts("Required fields " . implode(',', $missing) . " for $daoName are not present"));
 883     }
 884   }
 885
 886   return TRUE;
 887 }
 888
 889 /**
 890  * Check permissions for a given API call.
 891  *
 892  * @param $entity string API entity being accessed
 893  * @param $action string API action being performed
 894  * @param $params array  params of the API call
 895  * @param $throw bool    whether to throw exception instead of returning false
 896  *
 897  * @return bool whether the current API user has the permission to make the call
 898  */
 899 function _civicrm_api3_api_check_permission($entity, $action, &$params, $throw = TRUE) {
 900   // return early unless we’re told explicitly to do the permission check
 901   if (empty($params['check_permissions']) or $params['check_permissions'] == FALSE) {
 902     return TRUE;
 903   }
 904
 905   require_once 'CRM/Core/Permission.php';
 906
 907   require_once 'CRM/Core/DAO/.permissions.php';
 908   $permissions = _civicrm_api3_permissions($entity, $action, $params);
 909
 910   // $params might’ve been reset by the alterAPIPermissions() hook
 911   if (isset($params['check_permissions']) and $params['check_permissions'] == FALSE) {
 912     return TRUE;
 913   }
 914
 915   foreach ($permissions as $perm) {
 916     if (!CRM_Core_Permission::check($perm)) {
 917       if ($throw) {
 918         throw new Exception("API permission check failed for $entity/$action call; missing permission: $perm.");
 919       }
 920       else {
 921         return FALSE;
 922       }
 923     }
 924   }
 925   return TRUE;
 926 }
 927
 928 /*
 929  * Function to do a 'standard' api get - when the api is only doing a $bao->find then use this
 930  *
 931  * @param string $bao_name name of BAO
 932  * @param array $params params from api
 933  * @param bool $returnAsSuccess return in api success format
 934  */
 935 function _civicrm_api3_basic_get($bao_name, &$params, $returnAsSuccess = TRUE, $entity = "") {
 936   $bao = new $bao_name();
 937   _civicrm_api3_dao_set_filter($bao, $params, TRUE,$entity);
 938   if ($returnAsSuccess) {
 939     return civicrm_api3_create_success(_civicrm_api3_dao_to_array($bao, $params, FALSE, $entity), $params, $entity);
 940   }
 941   else {
 942     return _civicrm_api3_dao_to_array($bao, $params, FALSE, $entity);
 943   }
 944 }
 945
 946 /*
 947  * Function to do a 'standard' api create - when the api is only doing a $bao::create then use this
 948  * @param string $bao_name Name of BAO Class
 949  * @param array $params parameters passed into the api call
 950  * @param string $entity Entity - pass in if entity is non-standard & required $ids array
 951  */
 952 function _civicrm_api3_basic_create($bao_name, &$params, $entity = null) {
 953
 954   $args = array(&$params);
 955   if(!empty($entity)){
 956     $ids = array($entity => CRM_Utils_Array::value('id', $params));
 957     $args[] = &$ids;
 958   }
 959   if (method_exists($bao_name, 'create')) {
 960     $fct = 'create';
 961   }
 962   elseif (method_exists($bao_name, 'add')) {
 963     $fct = 'add';
 964   }
 965   if (!isset($fct)) {
 966     return civicrm_api3_create_error('Entity not created, missing create or add method for ' . $bao_name);
 967   }
 968   $bao = call_user_func_array(array($bao_name, $fct), $args);
 969   if (is_null($bao)) {
 970     return civicrm_api3_create_error('Entity not created ' . $bao_name . '::' . $fct);
 971   }
 972   else {
 973     $values = array();
 974     _civicrm_api3_object_to_array($bao, $values[$bao->id]);
 975     return civicrm_api3_create_success($values, $params, null, 'create', $bao);
 976   }
 977 }
 978
 979 /*
 980  * Function to do a 'standard' api del - when the api is only doing a $bao::del then use this
 981  * if api::del doesn't exist it will try DAO delete method
 982  */
 983 function _civicrm_api3_basic_delete($bao_name, &$params) {
 984
 985   civicrm_api3_verify_mandatory($params, NULL, array('id'));
 986   $args = array(&$params['id']);
 987   if (method_exists($bao_name, 'del')) {
 988     $bao = call_user_func_array(array($bao_name, 'del'), $args);
 989     return civicrm_api3_create_success(TRUE);
 990   }
 991   elseif (method_exists($bao_name, 'delete')) {
 992     $dao = new $bao_name();
 993     $dao->id = $params['id'];
 994     if ($dao->find()) {
 995       while ($dao->fetch()) {
 996         $dao->delete();
 997         return civicrm_api3_create_success();
 998       }
 999     }
1000     else {
1001       return civicrm_api3_create_error('Could not delete entity id ' . $params['id']);
1002     }
1003   }
1004
1005   return civicrm_api3_create_error('no delete method found');
1006 }
1007
1008 /*
1009  * Get custom data for the given entity & Add it to the returnArray as 'custom_123' = 'custom string' AND 'custom_123_1' = 'custom string'
1010  * Where 123 is field value & 1 is the id within the custom group data table (value ID)
1011  *
1012  * @param array $returnArray - array to append custom data too - generally $result[4] where 4 is the entity id.
1013  * @param string $entity  e.g membership, event
1014  * @param int $groupID - per CRM_Core_BAO_CustomGroup::getTree
1015  * @param int $subType e.g. membership_type_id where custom data doesn't apply to all membership types
1016  * @param string $subName - Subtype of entity
1017  *
1018  */
1019 function _civicrm_api3_custom_data_get(&$returnArray, $entity, $entity_id, $groupID = NULL, $subType = NULL, $subName = NULL) {
1020   require_once 'CRM/Core/BAO/CustomGroup.php';
1021   require_once 'CRM/Core/BAO/CustomField.php';
1022   $groupTree = &CRM_Core_BAO_CustomGroup::getTree($entity,
1023     CRM_Core_DAO::$_nullObject,
1024     $entity_id,
1025     $groupID,
1026     $subType,
1027     $subName
1028   );
1029   $groupTree = CRM_Core_BAO_CustomGroup::formatGroupTree($groupTree, 1, CRM_Core_DAO::$_nullObject);
1030   $customValues = array();
1031   CRM_Core_BAO_CustomGroup::setDefaults($groupTree, $customValues);
1032   if (!empty($customValues)) {
1033     foreach ($customValues as $key => $val) {
1034       if (strstr($key, '_id')) {
1035         $idkey = substr($key, 0, -3);
1036         $returnArray['custom_' . (CRM_Core_BAO_CustomField::getKeyID($idkey) . "_id")] = $val;
1037         $returnArray[$key] = $val;
1038       }
1039       else {
1040         // per standard - return custom_fieldID
1041         $returnArray['custom_' . (CRM_Core_BAO_CustomField::getKeyID($key))] = $val;
1042
1043         //not standard - but some api did this so guess we should keep - cheap as chips
1044         $returnArray[$key] = $val;
1045       }
1046     }
1047   }
1048 }
1049
1050 /*
1051  * Validate fields being passed into API. This function relies on the getFields function working accurately
1052  * for the given API. If error mode is set to TRUE then it will also check
1053  * foreign keys
1054  *
1055  * As of writing only date was implemented.
1056  * @param string $entity
1057  * @param string $action
1058  * @param array $params -
1059  * all variables are the same as per civicrm_api
1060  */
1061 function _civicrm_api3_validate_fields($entity, $action, &$params, $errorMode = NULL) {
1062   //skip any entities without working getfields functions
1063   $skippedEntities = array('entity', 'mailinggroup', 'customvalue', 'custom_value', 'mailing_group');
1064   if (in_array(strtolower($entity), $skippedEntities) || strtolower($action) == 'getfields') {
1065     return;
1066   }
1067   $fields = civicrm_api($entity, 'getfields', array('version' => 3, 'action' => $action));
1068   $fields = array_intersect_key($fields['values'], $params);
1069   foreach ($fields as $fieldname => $fieldInfo) {
1070     switch (CRM_Utils_Array::value('type', $fieldInfo)) {
1071       case CRM_Utils_Type::T_INT:
1072         //field is of type integer
1073         _civicrm_api3_validate_integer($params, $fieldname, $fieldInfo, $entity);
1074         break;
1075
1076       case 4:
1077       case 12:
1078         //field is of type date or datetime
1079         _civicrm_api3_validate_date($params, $fieldname, $fieldInfo);
1080         break;
1081     case 32://blob
1082         _civicrm_api3_validate_html($params, $fieldname, $fieldInfo);
1083         break;
1084       case CRM_Utils_Type::T_STRING:
1085
1086         _civicrm_api3_validate_string($params, $fieldname, $fieldInfo);
1087         break;
1088
1089       case CRM_Utils_Type::T_MONEY:
1090         if (!CRM_Utils_Rule::money($params[$fieldname])) {
1091           throw new Exception($fieldname . " is  not a valid amount: " . $params[$fieldname]);
1092         }
1093     }
1094
1095     // intensive checks - usually only called after DB level fail
1096     if (!empty($errorMode) && strtolower($action) == 'create') {
1097       if (CRM_Utils_Array::value('FKClassName', $fieldInfo)) {
1098         if (CRM_Utils_Array::value($fieldname, $params)) {
1099           _civicrm_api3_validate_constraint($params, $fieldname, $fieldInfo);
1100         }
1101         elseif (CRM_Utils_Array::value('required', $fieldInfo)) {
1102           throw new Exception("DB Constraint Violation - possibly $fieldname should possibly be marked as mandatory for this API. If so, please raise a bug report");
1103         }
1104       }
1105       if (CRM_Utils_Array::value('api.unique', $fieldInfo)) {
1106         $params['entity'] = $entity;
1107         _civicrm_api3_validate_uniquekey($params, $fieldname, $fieldInfo);
1108       }
1109     }
1110   }
1111 }
1112
1113 /*
1114  * Validate date fields being passed into API.
1115  * It currently converts both unique fields and DB field names to a mysql date.
1116  * @todo - probably the unique field handling & the if exists handling is now done before this
1117  * function is reached in the wrapper - can reduce this code down to assume we
1118  * are only checking the passed in field
1119  *
1120  * It also checks against the RULE:date function. This is a centralisation of code that was scattered and
1121  * may not be the best thing to do. There is no code level documentation on the existing functions to work off
1122  *
1123  * @param array $params params from civicrm_api
1124  * @param string $fieldname uniquename of field being checked
1125  * @param array $fieldinfo array of fields from getfields function
1126  */
1127 function _civicrm_api3_validate_date(&$params, &$fieldname, &$fieldInfo) {
1128   //should we check first to prevent it from being copied if they have passed in sql friendly format?
1129   if (CRM_Utils_Array::value($fieldInfo['name'], $params)) {
1130     //accept 'whatever strtotime accepts
1131     if (strtotime($params[$fieldInfo['name']]) === FALSE) {
1132       throw new Exception($fieldInfo['name'] . " is not a valid date: " . $params[$fieldInfo['name']]);
1133     }
1134     $params[$fieldInfo['name']] = CRM_Utils_Date::processDate($params[$fieldInfo['name']]);
1135   }
1136   if ((CRM_Utils_Array::value('name', $fieldInfo) != $fieldname) && CRM_Utils_Array::value($fieldname, $params)) {
1137     //If the unique field name differs from the db name & is set handle it here
1138     if (strtotime($params[$fieldname]) === FALSE) {
1139       throw new Exception($fieldname . " is not a valid date: " . $params[$fieldname]);
1140     }
1141     $params[$fieldname] = CRM_Utils_Date::processDate($params[$fieldname]);
1142   }
1143 }
1144 /*
1145  * Validate foreign constraint fields being passed into API.
1146  *
1147  * @param array $params params from civicrm_api
1148  * @param string $fieldname uniquename of field being checked
1149  * @param array $fieldinfo array of fields from getfields function
1150  */
1151 function _civicrm_api3_validate_constraint(&$params, &$fieldname, &$fieldInfo) {
1152   $file = str_replace('_', '/', $fieldInfo['FKClassName']) . ".php";
1153   require_once ($file);
1154   $dao = new $fieldInfo['FKClassName'];
1155   $dao->id = $params[$fieldname];
1156   $dao->selectAdd();
1157   $dao->selectAdd('id');
1158   if (!$dao->find()) {
1159     throw new Exception("$fieldname is not valid : " . $params[$fieldname]);
1160   }
1161 }
1162
1163 /*
1164  * Validate foreign constraint fields being passed into API.
1165  *
1166  * @param array $params params from civicrm_api
1167  * @param string $fieldname uniquename of field being checked
1168  * @param array $fieldinfo array of fields from getfields function
1169  */
1170 function _civicrm_api3_validate_uniquekey(&$params, &$fieldname, &$fieldInfo) {
1171   $existing = civicrm_api($params['entity'], 'get', array(
1172       'version' => $params['version'],
1173       $fieldname => $params[$fieldname],
1174     ));
1175   // an entry already exists for this unique field
1176   if ($existing['count'] == 1) {
1177     // question - could this ever be a security issue?
1178     throw new Exception("Field: `$fieldname` must be unique. An conflicting entity already exists - id: " . $existing['id']);
1179   }
1180 }
1181
1182 /**
1183  * Generic implementation of the "replace" action.
1184  *
1185  * Replace the old set of entities (matching some given keys) with a new set of
1186  * entities (matching the same keys).
1187  *
1188  * Note: This will verify that 'values' is present, but it does not directly verify
1189  * any other parameters.
1190  *
1191  * @param string $entity entity name
1192  * @param array $params params from civicrm_api, including:
1193  *   - 'values': an array of records to save
1194  *   - all other items: keys which identify new/pre-existing records
1195  */
1196 function _civicrm_api3_generic_replace($entity, $params) {
1197
1198   require_once 'CRM/Core/Transaction.php';
1199   $transaction = new CRM_Core_Transaction();
1200   try {
1201     if (!is_array($params['values'])) {
1202       throw new Exception("Mandatory key(s) missing from params array: values");
1203     }
1204
1205     // Extract the keys -- somewhat scary, don't think too hard about it
1206     $baseParams = $params;
1207     unset($baseParams['values']);
1208     unset($baseParams['sequential']);
1209
1210     // Lookup pre-existing records
1211     $preexisting = civicrm_api($entity, 'get', $baseParams, $params);
1212     if (civicrm_error($preexisting)) {
1213       $transaction->rollback();
1214       return $preexisting;
1215     }
1216
1217     // Save the new/updated records
1218     $creates = array();
1219     foreach ($params['values'] as $replacement) {
1220       // Sugar: Don't force clients to duplicate the 'key' data
1221       $replacement = array_merge($baseParams, $replacement);
1222       $action      = (isset($replacement['id']) || isset($replacement[$entity . '_id'])) ? 'update' : 'create';
1223       $create      = civicrm_api($entity, $action, $replacement);
1224       if (civicrm_error($create)) {
1225         $transaction->rollback();
1226         return $create;
1227       }
1228       foreach ($create['values'] as $entity_id => $entity_value) {
1229         $creates[$entity_id] = $entity_value;
1230       }
1231     }
1232
1233     // Remove stale records
1234     $staleIDs = array_diff(
1235       array_keys($preexisting['values']),
1236       array_keys($creates)
1237     );
1238     foreach ($staleIDs as $staleID) {
1239       $delete = civicrm_api($entity, 'delete', array(
1240           'version' => $params['version'],
1241           'id' => $staleID,
1242         ));
1243       if (civicrm_error($delete)) {
1244         $transaction->rollback();
1245         return $delete;
1246       }
1247     }
1248
1249     return civicrm_api3_create_success($creates, $params);
1250   }
1251   catch(PEAR_Exception $e) {
1252     $transaction->rollback();
1253     return civicrm_api3_create_error($e->getMessage());
1254   }
1255   catch(Exception $e) {
1256     $transaction->rollback();
1257     return civicrm_api3_create_error($e->getMessage());
1258   }
1259 }
1260
1261 /*
1262  * returns fields allowable by api
1263  * @param $entity string Entity to query
1264  * @param bool $unique index by unique fields?
1265  */
1266 function _civicrm_api_get_fields($entity, $unique = FALSE, &$params = array(
1267   )) {
1268   $unsetIfEmpty = array('dataPattern', 'headerPattern', 'default', 'export', 'import');
1269   $dao = _civicrm_api3_get_DAO($entity);
1270   if (empty($dao)) {
1271     return array();
1272   }
1273   $file = str_replace('_', '/', $dao) . ".php";
1274   require_once ($file);
1275   $d = new $dao();
1276   $fields = $d->fields();
1277   // replace uniqueNames by the normal names as the key
1278   if (empty($unique)) {
1279     foreach ($fields as $name => & $field) {
1280       //getting rid of unused attributes
1281       foreach ($unsetIfEmpty as $attr) {
1282         if (empty($field[$attr])) {
1283           unset($field[$attr]);
1284         }
1285       }
1286       if ($name == $field['name']) {
1287         continue;
1288       }
1289       if (array_key_exists($field['name'], $fields)) {
1290         $field['error'] = 'name conflict';
1291         // it should never happen, but better safe than sorry
1292         continue;
1293       }
1294       $fields[$field['name']] = $field;
1295       $fields[$field['name']]['uniqueName'] = $name;
1296       unset($fields[$name]);
1297     }
1298   }
1299   $fields += _civicrm_api_get_custom_fields($entity, $params);
1300   return $fields;
1301 }
1302
1303 /*
1304  * Return an array of fields for a given entity - this is the same as the BAO function but
1305  * fields are prefixed with 'custom_' to represent api params
1306  */
1307 function _civicrm_api_get_custom_fields($entity, &$params) {
1308   require_once 'CRM/Core/BAO/CustomField.php';
1309   $customfields = array();
1310   $entity = _civicrm_api_get_camel_name($entity);
1311   if (strtolower($entity) == 'contact') {
1312     $entity = CRM_Utils_Array::value('contact_type', $params);
1313   }
1314   $retrieveOnlyParent = FALSE;
1315   // we could / should probably test for other subtypes here - e.g. activity_type_id
1316   if($entity == 'Contact'){
1317     empty($params['contact_sub_type']);
1318   }
1319   $customfields = CRM_Core_BAO_CustomField::getFields($entity,
1320     FALSE,
1321     FALSE,
1322     CRM_Utils_Array::value('contact_sub_type', $params, FALSE),
1323     NULL,
1324     $retrieveOnlyParent,
1325     FALSE,
1326     FALSE
1327   );
1328   // find out if we have any requests to resolve options
1329   $getoptions = CRM_Utils_Array::value('get_options', CRM_Utils_Array::value('options',$params));
1330   if(!is_array($getoptions)){
1331       $getoptions = array($getoptions);
1332   }
1333
1334   foreach ($customfields as $key => $value) {
1335     $customfields['custom_' . $key] = $value;
1336    if(in_array('custom_' . $key, $getoptions)){
1337      $customfields['custom_' . $key]['options'] = CRM_Core_BAO_CustomOption::valuesByID($key);
1338    }
1339     unset($customfields[$key]);
1340   }
1341   return $customfields;
1342 }
1343 /*
1344  * Return array of defaults for the given API (function is a wrapper on getfields)
1345  */
1346 function _civicrm_api3_getdefaults($apiRequest) {
1347   $defaults = array();
1348
1349   $result = civicrm_api($apiRequest['entity'],
1350     'getfields',
1351     array(
1352       'version' => 3,
1353       'action' => $apiRequest['action'],
1354     )
1355   );
1356
1357   foreach ($result['values'] as $field => $values) {
1358     if (isset($values['api.default'])) {
1359       $defaults[$field] = $values['api.default'];
1360     }
1361   }
1362   return $defaults;
1363 }
1364
1365 /*
1366  * Return array of defaults for the given API (function is a wrapper on getfields)
1367  */
1368 function _civicrm_api3_getrequired($apiRequest) {
1369   $required = array('version');
1370
1371   $result = civicrm_api($apiRequest['entity'],
1372     'getfields',
1373     array(
1374       'version' => 3,
1375       'action' => $apiRequest['action'],
1376     )
1377   );
1378   foreach ($result['values'] as $field => $values) {
1379     if (CRM_Utils_Array::value('api.required', $values)) {
1380       $required[] = $field;
1381     }
1382   }
1383   return $required;
1384 }
1385
1386 /*
1387  * Fill params array with alternate (alias) values where a field has an alias and that is filled & the main field isn't
1388  * If multiple aliases the last takes precedence
1389  *
1390  * Function also swaps unique fields for non-unique fields & vice versa.
1391  */
1392 function _civicrm_api3_swap_out_aliases(&$apiRequest) {
1393   if (strtolower($apiRequest['action'] == 'getfields')) {
1394     if (CRM_Utils_Array::value('api_action', $apiRequest['params'])) {
1395       $apiRequest['params']['action'] = $apiRequest['params']['api_action'];
1396       unset($apiRequest['params']['api_action']);
1397     }
1398     return;
1399   }
1400   $result = civicrm_api($apiRequest['entity'],
1401     'getfields',
1402     array(
1403       'version' => 3,
1404       'action' => $apiRequest['action'],
1405     )
1406   );
1407
1408   foreach ($result['values'] as $field => $values) {
1409     $uniqueName = CRM_Utils_Array::value('uniqueName', $values);
1410     if (CRM_Utils_Array::value('api.aliases', $values)) {
1411       // if aliased field is not set we try to use field alias
1412       if (!isset($apiRequest['params'][$field])) {
1413         foreach ($values['api.aliases'] as $alias) {
1414           if (isset($apiRequest['params'][$alias])) {
1415             $apiRequest['params'][$field] = $apiRequest['params'][$alias];
1416           }
1417           //unset original field  nb - need to be careful with this as it may bring inconsistencies
1418           // out of the woodwork but will be implementing only as _spec function extended
1419           unset($apiRequest['params'][$alias]);
1420         }
1421       }
1422     }
1423     if (!isset($apiRequest['params'][$field])
1424       && CRM_Utils_Array::value('name', $values)
1425       && $field != $values['name']
1426       && isset($apiRequest['params'][$values['name']])
1427     ) {
1428       $apiRequest['params'][$field] = $apiRequest['params'][$values['name']];
1429       // note that it would make sense to unset the original field here but tests need to be in place first
1430     }
1431     if (!isset($apiRequest['params'][$field])
1432       && $uniqueName
1433       && $field != $uniqueName
1434       && array_key_exists($uniqueName, $apiRequest['params'])
1435       )
1436     {
1437       $apiRequest['params'][$field] = CRM_Utils_Array::value($values['uniqueName'], $apiRequest['params']);
1438       // note that it would make sense to unset the original field here but tests need to be in place first
1439     }
1440   }
1441
1442 }
1443 /*
1444  * Validate integer fields being passed into API.
1445  * It currently converts the incoming value 'user_contact_id' into the id of the currenty logged in user
1446  *
1447  * @param array $params params from civicrm_api
1448  * @param string $fieldname uniquename of field being checked
1449  * @param array $fieldinfo array of fields from getfields function
1450  */
1451 function _civicrm_api3_validate_integer(&$params, &$fieldname, &$fieldInfo, $entity) {
1452   //if fieldname exists in params
1453   if (CRM_Utils_Array::value($fieldname, $params)) {
1454     //if value = 'user_contact_id' replace value with logged in user id
1455     if ($params[$fieldname] == "user_contact_id") {
1456       $session = &CRM_Core_Session::singleton();
1457       $params[$fieldname] = $session->get('userID');
1458     }
1459     if (CRM_Utils_Array::value('pseudoconstant', $fieldInfo) ) {
1460       $constant = CRM_Utils_Array::value('options', $fieldInfo);
1461       if (is_numeric($params[$fieldname]) && !CRM_Utils_Array::value('FKClassName',$fieldInfo) && !array_key_exists($params[$fieldname], $fieldInfo['options'])) {
1462         throw new API_Exception("$fieldname is not valid", 2001, array('error_field' => $fieldname,"type"=>"integer"));
1463       }
1464     }
1465     // we are looking for strings that should be swapped out e.g swap 'Donation' to financial_type_id 1
1466     if (!is_numeric($params[$fieldname]) && !is_array($params[$fieldname])) {
1467       if(CRM_Utils_Array::value('FKClassName', $fieldInfo)){
1468         // we'll get the options for this now since we are doing a swap out
1469         $options = civicrm_api($entity, 'getoptions', array('version' => 3, 'field' => $fieldname));
1470         if(empty($options['is_error'])){
1471           $fieldInfo['options'] = $options['values'];
1472         }
1473       }
1474       if(!empty($fieldInfo['options'])){
1475         $numericvalue = array_search($params[$fieldname], $fieldInfo['options']);
1476         if (empty($numericvalue)) {
1477           throw new Exception("$fieldname " . $params[$fieldname] . " is not valid");
1478         }
1479         else {
1480           $params[$fieldname] = $numericvalue;
1481         }
1482       }
1483     }
1484
1485     // once we have done any swaps check our field length
1486     if(is_string($params[$fieldname]) &&
1487       CRM_Utils_Array::value('maxlength',$fieldInfo)
1488       && strlen($params[$fieldname]) > $fieldInfo['maxlength']
1489       ){
1490       throw new API_Exception( $params[$fieldname] . " is " . strlen($params[$fieldname]) . " characters  - longer than $fieldname length" . $fieldInfo['maxlength'] . ' characters',
1491         2100, array('field' => $fieldname, "max_length"=>$fieldInfo['maxlength'])
1492       );
1493     }
1494   }
1495 }
1496
1497 function _civicrm_api3_validate_html(&$params, &$fieldname, &$fieldInfo) {
1498   if ($value = CRM_Utils_Array::value($fieldname, $params)) {
1499     if (!CRM_Utils_Rule::xssString($value)) {
1500       throw new API_Exception('Illegal characters in input (potential scripting attack)',array("field"=>$fieldname,"error_code"=>"xss"));
1501     }
1502   }
1503 }
1504
1505 /*
1506  * Validate string fields being passed into API.
1507  * @param array $params params from civicrm_api
1508  * @param string $fieldname uniquename of field being checked
1509  * @param array $fieldinfo array of fields from getfields function
1510  */
1511 function _civicrm_api3_validate_string(&$params, &$fieldname, &$fieldInfo) {
1512   // If fieldname exists in params
1513   $value = (string) CRM_Utils_Array::value($fieldname, $params,'');
1514   if ($value ) {
1515     if (!CRM_Utils_Rule::xssString($value)) {
1516       throw new Exception('Illegal characters in input (potential scripting attack)');
1517     }
1518     if ($fieldname == 'currency') {
1519       if (!CRM_Utils_Rule::currencyCode($value)) {
1520         throw new Exception("Currency not a valid code: $value");
1521       }
1522     }
1523     if (!empty ($fieldInfo['options'])) {
1524       // Validate & swap out any pseudoconstants / options
1525       $options = $fieldInfo['options'];
1526       $lowerCaseOptions = array_map("strtolower", $options);
1527       // If value passed is not a key, it may be a label
1528       // Try to lookup key from label - if it can't be found throw error
1529       if (!isset($options[strtolower($value)]) && !isset($options[$value]) ) {
1530         if (!in_array(strtolower($value), $lowerCaseOptions)) {
1531           throw new Exception("$fieldname `$value` is not valid.");
1532         }
1533       }
1534     }
1535     // Check our field length
1536     elseif (is_string($value) && !empty($fieldInfo['maxlength']) && strlen($value) > $fieldInfo['maxlength']) {
1537       throw new API_Exception("Value for $fieldname is " . strlen($value) . " characters  - This field has a maxlength of {$fieldInfo['maxlength']} characters.",
1538         2100, array('field' => $fieldname)
1539       );
1540     }
1541   }
1542 }