api/v3/Contribution.php

   1 <?php
   2
   3 /*
   4  +--------------------------------------------------------------------+
   5  | CiviCRM version 4.4                                                |
   6  +--------------------------------------------------------------------+
   7  | Copyright CiviCRM LLC (c) 2004-2013                                |
   8  +--------------------------------------------------------------------+
   9  | This file is a part of CiviCRM.                                    |
  10  |                                                                    |
  11  | CiviCRM is free software; you can copy, modify, and distribute it  |
  12  | under the terms of the GNU Affero General Public License           |
  13  | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  14  |                                                                    |
  15  | CiviCRM is distributed in the hope that it will be useful, but     |
  16  | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  17  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  18  | See the GNU Affero General Public License for more details.        |
  19  |                                                                    |
  20  | You should have received a copy of the GNU Affero General Public   |
  21  | License and the CiviCRM Licensing Exception along                  |
  22  | with this program; if not, contact CiviCRM LLC                     |
  23  | at info[AT]civicrm[DOT]org. If you have questions about the        |
  24  | GNU Affero General Public License or the licensing of CiviCRM,     |
  25  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  26  +--------------------------------------------------------------------+
  27 */
  28
  29 /**
  30  * File for the CiviCRM APIv3 Contribution functions
  31  *
  32  * @package CiviCRM_APIv3
  33  * @subpackage API_Contribute
  34  *
  35  * @copyright CiviCRM LLC (c) 2004-2013
  36  * @version $Id: Contribution.php 30486 2010-11-02 16:12:09Z shot $
  37  *
  38  */
  39
  40 /**
  41  * Add or update a contribution
  42  *
  43  * @param  array   $params           (reference ) input parameters
  44  *
  45  * @return array  Api result array
  46  * @static void
  47  * @access public
  48  * @example ContributionCreate.php
  49  * {@getfields Contribution_create}
  50  */
  51 function civicrm_api3_contribution_create(&$params) {
  52   $values = array();
  53   _civicrm_api3_custom_format_params($params, $values, 'Contribution');
  54   $params = array_merge($params, $values);
  55
  56   //legacy soft credit handling - recommended approach is chaining
  57   if(!empty($params['soft_credit_to'])){
  58     $params['soft_credit'] = array(array(
  59       'contact_id' => $params['soft_credit_to'],
  60       'amount' => $params['total_amount']));
  61   }
  62
  63   if (CRM_Utils_Array::value('id', $params) && CRM_Utils_Array::value('contribution_status_id', $params)) {
  64     $error = array();
  65     //throw error for invalid status change such as setting completed back to pending
  66     //@todo this sort of validation belongs in the BAO not the API - if it is not an OK
  67     // action it needs to be blocked there. If it is Ok through a form it needs to be OK through the api
  68     CRM_Contribute_BAO_Contribution::checkStatusValidation(NULL, $params, $error);
  69     if (array_key_exists('contribution_status_id', $error)) {
  70       throw new API_Exception($error['contribution_status_id']);
  71     }
  72   }
  73   return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params, 'Contribution');
  74 }
  75
  76 /**
  77  * Adjust Metadata for Create action
  78  *
  79  * The metadata is used for setting defaults, documentation & validation
  80  * @param array $params array or parameters determined by getfields
  81  */
  82 function _civicrm_api3_contribution_create_spec(&$params) {
  83   $params['contact_id']['api.required'] = 1;
  84   $params['total_amount']['api.required'] = 1;
  85   $params['payment_instrument_id']['api.aliases'] = array('payment_instrument');
  86   $params['receive_date']['api.default'] = 'now';
  87   $params['payment_processor'] = array(
  88     'name' => 'payment_processor',
  89     'title' => 'Payment Processor ID',
  90     'description' => 'ID of payment processor used for this contribution',
  91     // field is called payment processor - not payment processor id but can only be one id so
  92     // it seems likely someone will fix it up one day to be more consistent - lets alias it from the start
  93     'api.aliases' => array('payment_processor_id'),
  94   );
  95   $params['financial_type_id']['api.aliases'] = array('contribution_type_id', 'contribution_type');
  96   $params['financial_type_id']['api.required'] = 1;
  97   $params['note'] = array(
  98     'name' => 'note',
  99     'uniqueName' => 'contribution_note',
 100     'title' => 'note',
 101     'type' => 2,
 102     'description' => 'Associated Note in the notes table',
 103   );
 104   $params['soft_credit_to'] = array(
 105     'name' => 'soft_credit_to',
 106     'title' => 'Soft Credit contact ID',
 107     'type' => 1,
 108     'description' => 'ID of Contact to be Soft credited to',
 109     'FKClassName' => 'CRM_Contact_DAO_Contact',
 110   );
 111   // note this is a recommended option but not adding as a default to avoid
 112   // creating unecessary changes for the dev
 113   $params['skipRecentView'] = array(
 114     'name' => 'skipRecentView',
 115     'title' => 'Skip adding to recent view',
 116     'type' => CRM_Utils_Type::T_BOOLEAN,
 117     'description' => 'Do not add to recent view (setting this improves performance)',
 118   );
 119   $params['skipLineItem'] = array(
 120     'name' => 'skipLineItem',
 121     'title' => 'Skip adding line items',
 122     'type' => 1,
 123     'api.default' => 0,
 124     'description' => 'Do not add line items by default (if you wish to add your own)',
 125   );
 126   $params['batch_id'] = array(
 127     'title' => 'Batch',
 128     'type' => 1,
 129     'description' => 'Batch which relevant transactions should be added to',
 130   );
 131 }
 132
 133 /**
 134  * Delete a contribution
 135  *
 136  * @param  array   $params           (reference ) input parameters
 137  *
 138  * @return boolean        true if success, else false
 139  * @static void
 140  * @access public
 141  * {@getfields Contribution_delete}
 142  * @example ContributionDelete.php
 143  */
 144 function civicrm_api3_contribution_delete($params) {
 145
 146   $contributionID = CRM_Utils_Array::value('contribution_id', $params) ? $params['contribution_id'] : $params['id'];
 147   if (CRM_Contribute_BAO_Contribution::deleteContribution($contributionID)) {
 148     return civicrm_api3_create_success(array($contributionID => 1));
 149   }
 150   else {
 151     return civicrm_api3_create_error('Could not delete contribution');
 152   }
 153 }
 154
 155 /**
 156  * modify metadata. Legacy support for contribution_id
 157  */
 158 function _civicrm_api3_contribution_delete_spec(&$params) {
 159   $params['id']['api.aliases'] = array('contribution_id');
 160 }
 161
 162 /**
 163  * Retrieve a set of contributions, given a set of input params
 164  *
 165  * @param  array   $params           (reference ) input parameters
 166  * @param array    $returnProperties Which properties should be included in the
 167  * returned Contribution object. If NULL, the default
 168  * set of properties will be included.
 169  *
 170  * @return array (reference )        array of contributions, if error an array with an error id and error message
 171  * @static void
 172  * @access public
 173  * {@getfields Contribution_get}
 174  * @example ContributionGet.php
 175  */
 176 function civicrm_api3_contribution_get($params) {
 177
 178   $mode = CRM_Contact_BAO_Query::MODE_CONTRIBUTE;
 179   $entity = 'contribution';
 180   list($dao, $query) = _civicrm_api3_get_query_object($params, $mode, $entity);
 181
 182   $contribution = array();
 183   while ($dao->fetch()) {
 184     //CRM-8662
 185     $contribution_details = $query->store($dao);
 186     $softContribution = CRM_Contribute_BAO_ContributionSoft::getSoftContribution($dao->contribution_id , TRUE);
 187     $contribution[$dao->contribution_id] = array_merge($contribution_details, $softContribution);
 188     if(isset($contribution[$dao->contribution_id]['financial_type_id'])){
 189       $contribution[$dao->contribution_id]['financial_type_id'] = $contribution[$dao->contribution_id]['financial_type_id'];
 190     }
 191     // format soft credit for backward compatibility
 192     _civicrm_api3_format_soft_credit($contribution[$dao->contribution_id]);
 193   }
 194   return civicrm_api3_create_success($contribution, $params, 'contribution', 'get', $dao);
 195 }
 196
 197 /**
 198  * This function is used to format the soft credit for backward compatibility
 199  * as of v4.4 we support multiple soft credit, so now contribution returns array with 'soft_credit' as key
 200  * but we still return first soft credit as a part of contribution array
 201  */
 202 function _civicrm_api3_format_soft_credit(&$contribution) {
 203   if (!empty($contribution['soft_credit'])) {
 204     $contribution['soft_credit_to'] = $contribution['soft_credit'][1]['contact_id'];
 205     $contribution['soft_credit_id'] = $contribution['soft_credit'][1]['soft_credit_id'];
 206   }
 207 }
 208
 209 /**
 210  * Adjust Metadata for Get action
 211  *
 212  * The metadata is used for setting defaults, documentation & validation
 213  * @param array $params array or parameters determined by getfields
 214  */
 215 function _civicrm_api3_contribution_get_spec(&$params) {
 216   $params['contribution_test']['api.default'] = 0;
 217   $params['financial_type_id']['api.aliases'] = array('contribution_type_id');
 218   $params['contact_id'] = $params['contribution_contact_id'];
 219   $params['contact_id']['api.aliases'] = array('contribution_contact_id');
 220   unset($params['contribution_contact_id']);
 221 }
 222
 223 /**
 224  * take the input parameter list as specified in the data model and
 225  * convert it into the same format that we use in QF and BAO object
 226  *
 227  * @param array  $params       Associative array of property name/value
 228  * pairs to insert in new contact.
 229  * @param array  $values       The reformatted properties that we can use internally
 230  * '
 231  *
 232  * @return array|CRM_Error
 233  * @access public
 234  */
 235 function _civicrm_api3_contribute_format_params($params, &$values, $create = FALSE) {
 236 //legacy way of formatting from v2 api - v3 way is to define metadata & do it in the api layer
 237   _civicrm_api3_filter_fields_for_bao('Contribution', $params, $values);
 238   return array();
 239 }
 240
 241 /**
 242  * Adjust Metadata for Transact action
 243  *
 244  * The metadata is used for setting defaults, documentation & validation
 245  * @param array $params array or parameters determined by getfields
 246  */
 247 function _civicrm_api3_contribution_transact_spec(&$params) {
 248   // This function calls create, so should inherit create spec
 249   _civicrm_api3_contribution_create_spec($params);
 250   $params['receive_date']['api.default'] = 'now';
 251 }
 252
 253 /**
 254  * Process a transaction and record it against the contact.
 255  *
 256  * @param  array   $params           (reference ) input parameters
 257  *
 258  * @return array (reference )        contribution of created or updated record (or a civicrm error)
 259  * @static void
 260  * @access public
 261  *
 262  */
 263 function civicrm_api3_contribution_transact($params) {
 264   // Set some params specific to payment processing
 265   $params['payment_processor_mode'] = empty($params['is_test']) ? 'live' : 'test';
 266   $params['amount'] = $params['total_amount'];
 267   if (!isset($params['net_amount'])) {
 268     $params['net_amount'] = $params['amount'];
 269   }
 270   if (!isset($params['invoiceID']) && isset($params['invoice_id'])) {
 271     $params['invoiceID'] = $params['invoice_id'];
 272   }
 273
 274   $paymentProcessor = CRM_Financial_BAO_PaymentProcessor::getPayment($params['payment_processor'], $params['payment_processor_mode']);
 275   if (civicrm_error($paymentProcessor)) {
 276     return $paymentProcessor;
 277   }
 278
 279   $payment = CRM_Core_Payment::singleton($params['payment_processor_mode'], $paymentProcessor);
 280   if (civicrm_error($payment)) {
 281     return $payment;
 282   }
 283
 284   $transaction = $payment->doDirectPayment($params);
 285   if (civicrm_error($transaction)) {
 286     return $transaction;
 287   }
 288
 289   // but actually, $payment->doDirectPayment() doesn't return a
 290   // CRM_Core_Error by itself
 291   if (is_object($transaction) && get_class($transaction) == 'CRM_Core_Error') {
 292     $errs = $transaction->getErrors();
 293     if (!empty($errs)) {
 294       $last_error = array_shift($errs);
 295       return CRM_Core_Error::createApiError($last_error['message']);
 296     }
 297   }
 298   $params['payment_instrument_id'] = CRM_Core_DAO::getFieldValue('CRM_Financial_DAO_PaymentProcessorType', $paymentProcessor['payment_processor_type_id'], 'payment_type') == 1 ? 'Credit Card' : 'Debit Card';
 299   return civicrm_api('contribution', 'create', $params);
 300 }
 301 /**
 302  * Send a contribution confirmation (receipt or invoice)
 303  * The appropriate online template will be used (the existence of related objects
 304  * (e.g. memberships ) will affect this selection
 305  * @param array $params input parameters
 306  * {@getfields Contribution_sendconfirmation}
 307  * @return array  Api result array
 308  * @static void
 309  * @access public
 310  *
 311  */
 312 function civicrm_api3_contribution_sendconfirmation($params) {
 313   $contribution = new CRM_Contribute_BAO_Contribution();
 314   $contribution->id = $params['id'];
 315   if (! $contribution->find(TRUE)) {
 316     throw new Exception('Contribution does not exist');
 317 }
 318   $input = $ids = $cvalues = array('receipt_from_email' => $params['receipt_from_email']);
 319   $contribution->loadRelatedObjects($input, $ids, FALSE, TRUE);
 320   $contribution->composeMessageArray($input, $ids, $cvalues, FALSE, FALSE);
 321 }
 322
 323 /**
 324  * Adjust Metadata for sendconfirmation action
 325  *
 326  * The metadata is used for setting defaults, documentation & validation
 327  * @param array $params array or parameters determined by getfields
 328  */
 329 function _civicrm_api3_contribution_sendconfirmation_spec(&$params) {
 330   $params['id'] = array(
 331     'api.required' => 1,
 332     'title' => 'Contribution ID'
 333   );
 334   $params['receipt_from_email'] = array(
 335     'api.required' =>1,
 336     'title' => 'From Email address (string) required until someone provides a patch :-)',
 337   );
 338   $params['receipt_from_name'] = array(
 339     'title' => 'From Name (string)',
 340   );
 341   $params['cc_receipt'] = array(
 342     'title' => 'CC Email address (string)',
 343   );
 344   $params['bcc_receipt'] = array(
 345     'title' => 'BCC Email address (string)',
 346   );
 347   $params['receipt_text'] = array(
 348     'title' => 'Message (string)',
 349   );
 350 }
 351
 352 /**
 353  * Complete an existing (pending) transaction, updating related entities (participant, membership, pledge etc)
 354  * and taking any complete actions from the contribution page (e.g. send receipt)
 355  *
 356  * @todo - most of this should live in the BAO layer but as we want it to be an addition
 357  * to 4.3 which is already stable we should add it to the api layer & re-factor into the BAO layer later
 358  *
 359  * @param array $params input parameters
 360  * {@getfields Contribution_completetransaction}
 361  * @return array  Api result array
 362  * @static void
 363  * @access public
 364  *
 365  */
 366 function civicrm_api3_contribution_completetransaction(&$params) {
 367
 368   $input = $ids = array();
 369   $contribution = new CRM_Contribute_BAO_Contribution();
 370   $contribution->id = $params['id'];
 371   $contribution->find(TRUE);
 372   if(!$contribution->id == $params['id']){
 373     throw new API_Exception('A valid contribution ID is required', 'invalid_data');
 374   }
 375   try {
 376     if(!$contribution->loadRelatedObjects($input, $ids, FALSE, TRUE)){
 377       throw new API_Exception('failed to load related objects');
 378     }
 379     $objects = $contribution->_relatedObjects;
 380     $objects['contribution'] = &$contribution;
 381     $input['component'] = $contribution->_component;
 382     $input['is_test'] = $contribution->is_test;
 383     $input['trxn_id']= !empty($params['trxn_id']) ? $params['trxn_id'] : $contribution->trxn_id;
 384     $input['amount'] = $contribution->total_amount;
 385     if(isset($params['is_email_receipt'])){
 386       $input['is_email_receipt'] = $params['is_email_receipt'];
 387     }
 388     // @todo required for base ipn but problematic as api layer handles this
 389     $transaction = new CRM_Core_Transaction();
 390     $ipn = new CRM_Core_Payment_BaseIPN();
 391     $ipn->completeTransaction($input, $ids, $objects, $transaction);
 392   }
 393   catch(Exception $e) {
 394     throw new API_Exception('failed to load related objects' . $e->getMessage() . "\n" . $e->getTraceAsString());
 395   }
 396 }
 397
 398 function _civicrm_api3_contribution_completetransaction(&$params) {
 399   $params['id'] = array(
 400     'title' => 'Contribution ID',
 401     'type' => CRM_Utils_Type::T_INT,
 402     'api.required' => TRUE,
 403   );
 404   $params['trxn_id'] = array(
 405     'title' => 'Transaction ID',
 406     'type' => CRM_Utils_Type::T_STRING,
 407   );
 408   $params['is_email_receipt'] = array(
 409     'title' => 'Send email Receipt?',
 410     'type' => CRM_Utils_Type::T_BOOLEAN,
 411   );
 412 }