api/v3/Order.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | Copyright CiviCRM LLC. All rights reserved.                        |
   5  |                                                                    |
   6  | This work is published under the GNU AGPLv3 license with some      |
   7  | permitted exceptions and without any warranty. For full license    |
   8  | and copyright information, see https://civicrm.org/licensing       |
   9  +--------------------------------------------------------------------+
  10  */
  11
  12 /**
  13  * This api exposes CiviCRM Order objects, an abstract entity
  14  * comprised of contributions and related line items.
  15  *
  16  * @package CiviCRM_APIv3
  17  */
  18
  19 /**
  20  * Retrieve a set of Order.
  21  *
  22  * @param array $params
  23  *  Input parameters.
  24  *
  25  * @return array
  26  *   Array of Order, if error an array with an error id and error message
  27  * @throws \CiviCRM_API3_Exception
  28  */
  29 function civicrm_api3_order_get(array $params): array {
  30   $contributions = [];
  31   $params['api.line_item.get'] = ['qty' => ['<>' => 0]];
  32   $isSequential = FALSE;
  33   if (!empty($params['sequential'])) {
  34     $params['sequential'] = 0;
  35     $isSequential = TRUE;
  36   }
  37   $result = civicrm_api3('Contribution', 'get', $params);
  38   if (!empty($result['values'])) {
  39     foreach ($result['values'] as $key => $contribution) {
  40       $contributions[$key] = $contribution;
  41       $contributions[$key]['line_items'] = $contribution['api.line_item.get']['values'];
  42       unset($contributions[$key]['api.line_item.get']);
  43     }
  44   }
  45   $params['sequential'] = $isSequential;
  46   return civicrm_api3_create_success($contributions, $params, 'Order', 'get');
  47 }
  48
  49 /**
  50  * Adjust Metadata for Get action.
  51  *
  52  * The metadata is used for setting defaults, documentation & validation.
  53  *
  54  * @param array $params
  55  *   Array of parameters determined by getfields.
  56  */
  57 function _civicrm_api3_order_get_spec(array &$params) {
  58   $params['id']['api.aliases'] = ['order_id'];
  59   $params['id']['title'] = ts('Contribution / Order ID');
  60 }
  61
  62 /**
  63  * Add or update a Order.
  64  *
  65  * @param array $params
  66  *   Input parameters.
  67  *
  68  * @return array
  69  *   Api result array
  70  *
  71  * @throws \CiviCRM_API3_Exception
  72  * @throws API_Exception
  73  */
  74 function civicrm_api3_order_create(array $params): array {
  75   civicrm_api3_verify_one_mandatory($params, NULL, ['line_items', 'total_amount']);
  76
  77   $params['contribution_status_id'] = 'Pending';
  78   $order = new CRM_Financial_BAO_Order();
  79   $order->setDefaultFinancialTypeID($params['financial_type_id'] ?? NULL);
  80
  81   if (!empty($params['line_items']) && is_array($params['line_items'])) {
  82     CRM_Contribute_BAO_Contribution::checkLineItems($params);
  83     foreach ($params['line_items'] as $index => $lineItems) {
  84       foreach ($lineItems['line_item'] as $innerIndex => $lineItem) {
  85         $lineIndex = $index . '+' . $innerIndex;
  86         $order->setLineItem($lineItem, $lineIndex);
  87       }
  88
  89       $entityParams = $lineItems['params'] ?? NULL;
  90
  91       if ($entityParams && $order->getLineItemEntity($lineIndex) !== 'contribution') {
  92         switch ($order->getLineItemEntity($lineIndex)) {
  93           case 'participant':
  94             if (isset($entityParams['participant_status_id'])
  95               && (!CRM_Event_BAO_ParticipantStatusType::getIsValidStatusForClass($entityParams['participant_status_id'], 'Pending'))) {
  96               throw new CiviCRM_API3_Exception('Creating a participant via the Order API with a non "pending" status is not supported');
  97             }
  98             $entityParams['participant_status_id'] = $entityParams['participant_status_id'] ?? 'Pending from incomplete transaction';
  99             $entityParams['status_id'] = $entityParams['participant_status_id'];
 100             $entityParams['skipLineItem'] = TRUE;
 101             $entityResult = civicrm_api3('Participant', 'create', $entityParams);
 102             // @todo - once membership is cleaned up & financial validation tests are extended
 103             // we can look at removing this - some weird handling in removeFinancialAccounts
 104             $params['contribution_mode'] = 'participant';
 105             $params['participant_id'] = $entityResult['id'];
 106             break;
 107
 108           case 'membership':
 109             $entityParams['status_id'] = 'Pending';
 110             if (!empty($params['contribution_recur_id'])) {
 111               $entityParams['contribution_recur_id'] = $params['contribution_recur_id'];
 112             }
 113             $entityParams['skipLineItem'] = TRUE;
 114             $entityResult = civicrm_api3('Membership', 'create', $entityParams);
 115             break;
 116
 117         }
 118
 119         foreach ($lineItems['line_item'] as $innerIndex => $lineItem) {
 120           $lineIndex = $index . '+' . $innerIndex;
 121           $order->setLineItemValue('entity_id', $entityResult['id'], $lineIndex);
 122         }
 123       }
 124     }
 125     $priceSetID = $order->getPriceSetID();
 126     $params['line_item'][$priceSetID] = $order->getLineItems();
 127   }
 128   else {
 129     $order->setPriceSetToDefault('contribution');
 130   }
 131
 132   $contributionParams = $params;
 133   // If this is nested we need to set sequential to 0 as sequential handling is done
 134   // in create_success & id will be miscalculated...
 135   $contributionParams['sequential'] = 0;
 136   foreach ($contributionParams as $key => $value) {
 137     // Unset chained keys so the code does not attempt to do this chaining twice.
 138     // e.g if calling 'api.Payment.create' We want to finish creating the order first.
 139     // it would probably be better to have a full whitelist of contributionParams
 140     if (substr($key, 0, 3) === 'api') {
 141       unset($contributionParams[$key]);
 142     }
 143   }
 144
 145   $contribution = civicrm_api3('Contribution', 'create', $contributionParams);
 146   $contribution['values'][$contribution['id']]['line_item'] = array_values($order->getLineItems());
 147
 148   return civicrm_api3_create_success($contribution['values'] ?? [], $params, 'Order', 'create');
 149 }
 150
 151 /**
 152  * Delete a Order.
 153  *
 154  * @param array $params
 155  *   Input parameters.
 156  *
 157  * @return array
 158  * @throws API_Exception
 159  * @throws CiviCRM_API3_Exception
 160  */
 161 function civicrm_api3_order_delete(array $params): array {
 162   $contribution = civicrm_api3('Contribution', 'get', [
 163     'return' => ['is_test'],
 164     'id' => $params['id'],
 165   ]);
 166   if ($contribution['id'] && $contribution['values'][$contribution['id']]['is_test'] == TRUE) {
 167     $result = civicrm_api3('Contribution', 'delete', $params);
 168   }
 169   else {
 170     throw new API_Exception('Only test orders can be deleted.');
 171   }
 172   return civicrm_api3_create_success($result['values'], $params, 'Order', 'delete');
 173 }
 174
 175 /**
 176  * Cancel an Order.
 177  *
 178  * @param array $params
 179  *   Input parameters.
 180  *
 181  * @return array
 182  * @throws \CiviCRM_API3_Exception
 183  */
 184 function civicrm_api3_order_cancel(array $params) {
 185   $contributionStatuses = CRM_Contribute_PseudoConstant::contributionStatus(NULL, 'name');
 186   $params['contribution_status_id'] = array_search('Cancelled', $contributionStatuses);
 187   $result = civicrm_api3('Contribution', 'create', $params);
 188   return civicrm_api3_create_success($result['values'], $params, 'Order', 'cancel');
 189 }
 190
 191 /**
 192  * Adjust Metadata for Cancel action.
 193  *
 194  * The metadata is used for setting defaults, documentation & validation.
 195  *
 196  * @param array $params
 197  *   Array of parameters determined by getfields.
 198  */
 199 function _civicrm_api3_order_cancel_spec(array &$params) {
 200   $params['contribution_id'] = [
 201     'api.required' => 1,
 202     'title' => 'Contribution ID',
 203     'type' => CRM_Utils_Type::T_INT,
 204   ];
 205 }
 206
 207 /**
 208  * Adjust Metadata for Create action.
 209  *
 210  * The metadata is used for setting defaults, documentation & validation.
 211  *
 212  * @param array $params
 213  *   Array of parameters determined by getfields.
 214  */
 215 function _civicrm_api3_order_create_spec(array &$params) {
 216   $params['contact_id'] = [
 217     'name' => 'contact_id',
 218     'title' => 'Contact ID',
 219     'type' => CRM_Utils_Type::T_INT,
 220     'api.required' => TRUE,
 221   ];
 222   $params['total_amount'] = [
 223     'name' => 'total_amount',
 224     'title' => 'Total Amount',
 225   ];
 226   $params['skipCleanMoney'] = [
 227     'api.default' => TRUE,
 228     'title' => 'Do not attempt to convert money values',
 229     'type' => CRM_Utils_Type::T_BOOLEAN,
 230   ];
 231   $params['financial_type_id'] = [
 232     'name' => 'financial_type_id',
 233     'title' => 'Financial Type',
 234     'type' => CRM_Utils_Type::T_INT,
 235     'api.required' => TRUE,
 236     'table_name' => 'civicrm_contribution',
 237     'entity' => 'Contribution',
 238     'bao' => 'CRM_Contribute_BAO_Contribution',
 239     'pseudoconstant' => [
 240       'table' => 'civicrm_financial_type',
 241       'keyColumn' => 'id',
 242       'labelColumn' => 'name',
 243     ],
 244   ];
 245 }
 246
 247 /**
 248  * Adjust Metadata for Delete action.
 249  *
 250  * The metadata is used for setting defaults, documentation & validation.
 251  *
 252  * @param array $params
 253  *   Array of parameters determined by getfields.
 254  */
 255 function _civicrm_api3_order_delete_spec(array &$params) {
 256   $params['contribution_id'] = [
 257     'api.required' => TRUE,
 258     'title' => 'Contribution ID',
 259     'type' => CRM_Utils_Type::T_INT,
 260   ];
 261   $params['id']['api.aliases'] = ['contribution_id'];
 262 }