Merge remote-tracking branch 'origin/4.4' into 4.4-4.5-2014-09-14-13-58-42

[civicrm-core.git] / api / v3 / Contribution.php

diff --git a/api/v3/Contribution.php b/api/v3/Contribution.php
index 1385765a32f558163db74ed1d207fc1fb6d55b3a..a873073d85f434d040aa29970300fd545f6c8081 100644 (file)
--- a/api/v3/Contribution.php
+++ b/api/v3/Contribution.php
@@ -2,9 +2,9 @@
 
 /*
  +--------------------------------------------------------------------+
- | CiviCRM version 4.4                                                |
+ | CiviCRM version 4.5                                                |
  +--------------------------------------------------------------------+
- | Copyright CiviCRM LLC (c) 2004-2013                                |
+ | Copyright CiviCRM LLC (c) 2004-2014                                |
  +--------------------------------------------------------------------+
  | This file is a part of CiviCRM.                                    |
  |                                                                    |
@@ -32,7 +32,7 @@
  * @package CiviCRM_APIv3
  * @subpackage API_Contribute
  *
- * @copyright CiviCRM LLC (c) 2004-2013
+ * @copyright CiviCRM LLC (c) 2004-2014
  * @version $Id: Contribution.php 30486 2010-11-02 16:12:09Z shot $
  *
  */
@@ -40,8 +40,9 @@
 /**
  * Add or update a contribution
  *
- * @param  array   $params           (reference ) input parameters
+ * @param  array $params (reference ) input parameters
  *
+ * @throws API_Exception
  * @return array  Api result array
  * @static void
  * @access public
@@ -60,7 +61,7 @@ function civicrm_api3_contribution_create(&$params) {
       'amount' => $params['total_amount']));
   }
 
-  if (CRM_Utils_Array::value('id', $params) && CRM_Utils_Array::value('contribution_status_id', $params)) {
+  if (!empty($params['id']) && !empty($params['contribution_status_id'])) {
     $error = array();
     //throw error for invalid status change such as setting completed back to pending
     //@todo this sort of validation belongs in the BAO not the API - if it is not an OK
@@ -109,7 +110,7 @@ function _civicrm_api3_contribution_create_spec(&$params) {
     'FKClassName' => 'CRM_Contact_DAO_Contact',
   );
   // note this is a recommended option but not adding as a default to avoid
-  // creating unecessary changes for the dev
+  // creating unnecessary changes for the dev
   $params['skipRecentView'] = array(
     'name' => 'skipRecentView',
     'title' => 'Skip adding to recent view',
@@ -143,7 +144,7 @@ function _civicrm_api3_contribution_create_spec(&$params) {
  */
 function civicrm_api3_contribution_delete($params) {
 
-  $contributionID = CRM_Utils_Array::value('contribution_id', $params) ? $params['contribution_id'] : $params['id'];
+  $contributionID = !empty($params['contribution_id']) ? $params['contribution_id'] : $params['id'];
   if (CRM_Contribute_BAO_Contribution::deleteContribution($contributionID)) {
     return civicrm_api3_create_success(array($contributionID => 1));
   }
@@ -162,8 +163,9 @@ function _civicrm_api3_contribution_delete_spec(&$params) {
 /**
  * Retrieve a set of contributions, given a set of input params
  *
- * @param  array   $params           (reference ) input parameters
- * @param array    $returnProperties Which properties should be included in the
+ * @param  array $params (reference ) input parameters
+ *
+ * @internal param array $returnProperties Which properties should be included in the
  * returned Contribution object. If NULL, the default
  * set of properties will be included.
  *
@@ -214,6 +216,7 @@ function _civicrm_api3_format_soft_credit(&$contribution) {
  */
 function _civicrm_api3_contribution_get_spec(&$params) {
   $params['contribution_test']['api.default'] = 0;
+  $params['contribution_test']['title'] = 'Get Test Contributions?';
   $params['financial_type_id']['api.aliases'] = array('contribution_type_id');
   $params['contact_id'] = $params['contribution_contact_id'];
   $params['contact_id']['api.aliases'] = array('contribution_contact_id');
@@ -224,11 +227,13 @@ function _civicrm_api3_contribution_get_spec(&$params) {
  * take the input parameter list as specified in the data model and
  * convert it into the same format that we use in QF and BAO object
  *
- * @param array  $params       Associative array of property name/value
+ * @param array $params Associative array of property name/value
  * pairs to insert in new contact.
- * @param array  $values       The reformatted properties that we can use internally
+ * @param array $values The reformatted properties that we can use internally
  * '
  *
+ * @param bool $create
+ *
  * @return array|CRM_Error
  * @access public
  */
@@ -245,8 +250,8 @@ function _civicrm_api3_contribute_format_params($params, &$values, $create = FAL
  * @param array $params array or parameters determined by getfields
  */
 function _civicrm_api3_contribution_transact_spec(&$params) {
-  // This function calls create, so should inherit create spec
-  _civicrm_api3_contribution_create_spec($params);
+  $fields = civicrm_api3('contribution', 'getfields', array('action' => 'create'));
+  $params = array_merge($params, $fields['values']);
   $params['receive_date']['api.default'] = 'now';
 }
 
@@ -298,16 +303,19 @@ function civicrm_api3_contribution_transact($params) {
   $params['payment_instrument_id'] = CRM_Core_DAO::getFieldValue('CRM_Financial_DAO_PaymentProcessorType', $paymentProcessor['payment_processor_type_id'], 'payment_type') == 1 ? 'Credit Card' : 'Debit Card';
   return civicrm_api('contribution', 'create', $params);
 }
+
 /**
  * Send a contribution confirmation (receipt or invoice)
  * The appropriate online template will be used (the existence of related objects
  * (e.g. memberships ) will affect this selection
+ *
  * @param array $params input parameters
  * {@getfields Contribution_sendconfirmation}
+ *
+ * @throws Exception
  * @return array  Api result array
  * @static void
  * @access public
- *
  */
 function civicrm_api3_contribution_sendconfirmation($params) {
   $contribution = new CRM_Contribute_BAO_Contribution();
@@ -358,10 +366,11 @@ function _civicrm_api3_contribution_sendconfirmation_spec(&$params) {
  *
  * @param array $params input parameters
  * {@getfields Contribution_completetransaction}
+ *
+ * @throws API_Exception
  * @return array  Api result array
  * @static void
  * @access public
- *
  */
 function civicrm_api3_contribution_completetransaction(&$params) {
 
@@ -376,6 +385,9 @@ function civicrm_api3_contribution_completetransaction(&$params) {
     if(!$contribution->loadRelatedObjects($input, $ids, FALSE, TRUE)){
       throw new API_Exception('failed to load related objects');
     }
+    elseif ($contribution->contribution_status_id == CRM_Core_OptionGroup::getValue('contribution_status', 'Completed', 'name')) {
+      throw new API_Exception(ts('Contribution already completed'));
+    }
     $objects = $contribution->_relatedObjects;
     $objects['contribution'] = &$contribution;
     $input['component'] = $contribution->_component;
@@ -395,6 +407,9 @@ function civicrm_api3_contribution_completetransaction(&$params) {
   }
 }
 
+/**
+ * @param $params
+ */
 function _civicrm_api3_contribution_completetransaction(&$params) {
   $params['id'] = array(
     'title' => 'Contribution ID',