api/v3/Contribution.php

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