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             $entityParams['skipLineItem'] = TRUE;
 111             $entityResult = civicrm_api3('Membership', 'create', $entityParams);
 112             break;
 113         }
 114
 115         foreach ($lineItems['line_item'] as $innerIndex => $lineItem) {
 116           $lineIndex = $index . '+' . $innerIndex;
 117           $order->setLineItemValue('entity_id', $entityResult['id'], $lineIndex);
 118         }
 119       }
 120     }
 121     $priceSetID = $order->getPriceSetID();
 122     $params['line_item'][$priceSetID] = $order->getLineItems();
 123   }
 124   else {
 125     $order->setPriceSetToDefault('contribution');
 126   }
 127
 128   $contributionParams = $params;
 129   // If this is nested we need to set sequential to 0 as sequential handling is done
 130   // in create_success & id will be miscalculated...
 131   $contributionParams['sequential'] = 0;
 132   foreach ($contributionParams as $key => $value) {
 133     // Unset chained keys so the code does not attempt to do this chaining twice.
 134     // e.g if calling 'api.Payment.create' We want to finish creating the order first.
 135     // it would probably be better to have a full whitelist of contributionParams
 136     if (substr($key, 0, 3) === 'api') {
 137       unset($contributionParams[$key]);
 138     }
 139   }
 140
 141   $contribution = civicrm_api3('Contribution', 'create', $contributionParams);
 142   $contribution['values'][$contribution['id']]['line_item'] = $order->getLineItems();
 143
 144   return civicrm_api3_create_success($contribution['values'] ?? [], $params, 'Order', 'create');
 145 }
 146
 147 /**
 148  * Delete a Order.
 149  *
 150  * @param array $params
 151  *   Input parameters.
 152  *
 153  * @return array
 154  * @throws API_Exception
 155  * @throws CiviCRM_API3_Exception
 156  */
 157 function civicrm_api3_order_delete(array $params): array {
 158   $contribution = civicrm_api3('Contribution', 'get', [
 159     'return' => ['is_test'],
 160     'id' => $params['id'],
 161   ]);
 162   if ($contribution['id'] && $contribution['values'][$contribution['id']]['is_test'] == TRUE) {
 163     $result = civicrm_api3('Contribution', 'delete', $params);
 164   }
 165   else {
 166     throw new API_Exception('Only test orders can be deleted.');
 167   }
 168   return civicrm_api3_create_success($result['values'], $params, 'Order', 'delete');
 169 }
 170
 171 /**
 172  * Cancel an Order.
 173  *
 174  * @param array $params
 175  *   Input parameters.
 176  *
 177  * @return array
 178  * @throws \CiviCRM_API3_Exception
 179  */
 180 function civicrm_api3_order_cancel(array $params) {
 181   $contributionStatuses = CRM_Contribute_PseudoConstant::contributionStatus(NULL, 'name');
 182   $params['contribution_status_id'] = array_search('Cancelled', $contributionStatuses);
 183   $result = civicrm_api3('Contribution', 'create', $params);
 184   return civicrm_api3_create_success($result['values'], $params, 'Order', 'cancel');
 185 }
 186
 187 /**
 188  * Adjust Metadata for Cancel action.
 189  *
 190  * The metadata is used for setting defaults, documentation & validation.
 191  *
 192  * @param array $params
 193  *   Array of parameters determined by getfields.
 194  */
 195 function _civicrm_api3_order_cancel_spec(array &$params) {
 196   $params['contribution_id'] = [
 197     'api.required' => 1,
 198     'title' => 'Contribution ID',
 199     'type' => CRM_Utils_Type::T_INT,
 200   ];
 201 }
 202
 203 /**
 204  * Adjust Metadata for Create action.
 205  *
 206  * The metadata is used for setting defaults, documentation & validation.
 207  *
 208  * @param array $params
 209  *   Array of parameters determined by getfields.
 210  */
 211 function _civicrm_api3_order_create_spec(array &$params) {
 212   $params['contact_id'] = [
 213     'name' => 'contact_id',
 214     'title' => 'Contact ID',
 215     'type' => CRM_Utils_Type::T_INT,
 216     'api.required' => TRUE,
 217   ];
 218   $params['total_amount'] = [
 219     'name' => 'total_amount',
 220     'title' => 'Total Amount',
 221   ];
 222   $params['skipCleanMoney'] = [
 223     'api.default' => TRUE,
 224     'title' => 'Do not attempt to convert money values',
 225     'type' => CRM_Utils_Type::T_BOOLEAN,
 226   ];
 227   $params['financial_type_id'] = [
 228     'name' => 'financial_type_id',
 229     'title' => 'Financial Type',
 230     'type' => CRM_Utils_Type::T_INT,
 231     'api.required' => TRUE,
 232     'table_name' => 'civicrm_contribution',
 233     'entity' => 'Contribution',
 234     'bao' => 'CRM_Contribute_BAO_Contribution',
 235     'pseudoconstant' => [
 236       'table' => 'civicrm_financial_type',
 237       'keyColumn' => 'id',
 238       'labelColumn' => 'name',
 239     ],
 240   ];
 241 }
 242
 243 /**
 244  * Adjust Metadata for Delete action.
 245  *
 246  * The metadata is used for setting defaults, documentation & validation.
 247  *
 248  * @param array $params
 249  *   Array of parameters determined by getfields.
 250  */
 251 function _civicrm_api3_order_delete_spec(array &$params) {
 252   $params['contribution_id'] = [
 253     'api.required' => TRUE,
 254     'title' => 'Contribution ID',
 255     'type' => CRM_Utils_Type::T_INT,
 256   ];
 257   $params['id']['api.aliases'] = ['contribution_id'];
 258 }