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 use Civi\Api4\Membership;
  20
  21 /**
  22  * Retrieve a set of Order.
  23  *
  24  * @param array $params
  25  *  Input parameters.
  26  *
  27  * @return array
  28  *   Array of Order, if error an array with an error id and error message
  29  * @throws \CiviCRM_API3_Exception
  30  */
  31 function civicrm_api3_order_get(array $params): array {
  32   $contributions = [];
  33   $params['api.line_item.get'] = ['qty' => ['<>' => 0]];
  34   $isSequential = FALSE;
  35   if (!empty($params['sequential'])) {
  36     $params['sequential'] = 0;
  37     $isSequential = TRUE;
  38   }
  39   $result = civicrm_api3('Contribution', 'get', $params);
  40   if (!empty($result['values'])) {
  41     foreach ($result['values'] as $key => $contribution) {
  42       $contributions[$key] = $contribution;
  43       $contributions[$key]['line_items'] = $contribution['api.line_item.get']['values'];
  44       unset($contributions[$key]['api.line_item.get']);
  45     }
  46   }
  47   $params['sequential'] = $isSequential;
  48   return civicrm_api3_create_success($contributions, $params, 'Order', 'get');
  49 }
  50
  51 /**
  52  * Adjust Metadata for Get action.
  53  *
  54  * The metadata is used for setting defaults, documentation & validation.
  55  *
  56  * @param array $params
  57  *   Array of parameters determined by getfields.
  58  */
  59 function _civicrm_api3_order_get_spec(array &$params) {
  60   $params['id']['api.aliases'] = ['order_id'];
  61   $params['id']['title'] = ts('Contribution / Order ID');
  62 }
  63
  64 /**
  65  * Add or update a Order.
  66  *
  67  * @param array $params
  68  *   Input parameters.
  69  *
  70  * @return array
  71  *   Api result array
  72  *
  73  * @throws \CiviCRM_API3_Exception
  74  * @throws API_Exception
  75  */
  76 function civicrm_api3_order_create(array $params): array {
  77   civicrm_api3_verify_one_mandatory($params, NULL, ['line_items', 'total_amount']);
  78   if (empty($params['skipCleanMoney'])) {
  79     // We have to do this for v3 api - sadly. For v4 it will be no more.
  80     foreach (['total_amount', 'net_amount', 'fee_amount', 'non_deductible_amount'] as $field) {
  81       if (isset($params[$field])) {
  82         $params[$field] = CRM_Utils_Rule::cleanMoney($params[$field]);
  83       }
  84     }
  85     $params['skipCleanMoney'] = TRUE;
  86   }
  87   $params['contribution_status_id'] = 'Pending';
  88   $order = new CRM_Financial_BAO_Order();
  89   $order->setDefaultFinancialTypeID($params['financial_type_id'] ?? NULL);
  90
  91   if (!empty($params['line_items']) && is_array($params['line_items'])) {
  92     foreach ($params['line_items'] as $index => $lineItems) {
  93       if (!empty($lineItems['params'])) {
  94         $order->setEntityParameters($lineItems['params'], $index);
  95       }
  96       foreach ($lineItems['line_item'] as $innerIndex => $lineItem) {
  97         // For historical reasons it might be name.
  98         if (!empty($lineItem['membership_type_id']) && !is_numeric($lineItem['membership_type_id'])) {
  99           $lineItem['membership_type_id'] = CRM_Core_PseudoConstant::getKey('CRM_Member_BAO_Membership', 'membership_type_id', $lineItems['params']['membership_type_id']);
 100         }
 101         $lineIndex = $index . '+' . $innerIndex;
 102         $order->setLineItem($lineItem, $lineIndex);
 103         $order->addLineItemToEntityParameters($lineIndex, $index);
 104       }
 105     }
 106   }
 107   else {
 108     $order->setPriceSetToDefault('contribution');
 109     $order->setOverrideTotalAmount((float) $params['total_amount']);
 110     $order->setLineItem([], 0);
 111   }
 112   // Only check the amount if line items are set because that is what we have historically
 113   // done and total amount is historically only inclusive of tax_amount IF
 114   // tax amount is also passed in it seems
 115   if (isset($params['total_amount']) && !empty($params['line_items'])) {
 116     $currency = $params['currency'] ?? CRM_Core_Config::singleton()->defaultCurrency;
 117     if (!CRM_Utils_Money::equals($params['total_amount'], $order->getTotalAmount(), $currency)) {
 118       throw new CRM_Contribute_Exception_CheckLineItemsException();
 119     }
 120   }
 121   $params['total_amount'] = $order->getTotalAmount();
 122   if (!isset($params['tax_amount'])) {
 123     // @todo always calculate tax amount - left for now
 124     // for webform
 125     $params['tax_amount'] = $order->getTotalTaxAmount();
 126   }
 127
 128   foreach ($order->getEntitiesToCreate() as $entityParams) {
 129     if ($entityParams['entity'] === 'participant') {
 130       if (isset($entityParams['participant_status_id'])
 131         && (!CRM_Event_BAO_ParticipantStatusType::getIsValidStatusForClass($entityParams['participant_status_id'], 'Pending'))) {
 132         throw new CiviCRM_API3_Exception('Creating a participant via the Order API with a non "pending" status is not supported');
 133       }
 134       $entityParams['participant_status_id'] = $entityParams['participant_status_id'] ?? 'Pending from incomplete transaction';
 135       $entityParams['status_id'] = $entityParams['participant_status_id'];
 136       $entityParams['skipLineItem'] = TRUE;
 137       $entityResult = civicrm_api3('Participant', 'create', $entityParams);
 138       // @todo - once membership is cleaned up & financial validation tests are extended
 139       // we can look at removing this - some weird handling in removeFinancialAccounts
 140       $params['contribution_mode'] = 'participant';
 141       $params['participant_id'] = $entityResult['id'];
 142       foreach ($entityParams['line_references'] as $lineIndex) {
 143         $order->setLineItemValue('entity_id', $entityResult['id'], $lineIndex);
 144       }
 145     }
 146
 147     if ($entityParams['entity'] === 'membership') {
 148       if (empty($entityParams['id'])) {
 149         $entityParams['status_id:name'] = 'Pending';
 150       }
 151       if (!empty($params['contribution_recur_id'])) {
 152         $entityParams['contribution_recur_id'] = $params['contribution_recur_id'];
 153       }
 154       // At this stage we need to get this passed through.
 155       $entityParams['version'] = 4;
 156       _order_create_wrangle_membership_params($entityParams);
 157
 158       $membershipID = Membership::save($params['check_permissions'] ?? FALSE)->setRecords([$entityParams])->execute()->first()['id'];
 159       foreach ($entityParams['line_references'] as $lineIndex) {
 160         $order->setLineItemValue('entity_id', $membershipID, $lineIndex);
 161       }
 162     }
 163   }
 164
 165   $params['line_item'][$order->getPriceSetID()] = $order->getLineItems();
 166
 167   $contributionParams = $params;
 168   // If this is nested we need to set sequential to 0 as sequential handling is done
 169   // in create_success & id will be miscalculated...
 170   $contributionParams['sequential'] = 0;
 171   foreach ($contributionParams as $key => $value) {
 172     // Unset chained keys so the code does not attempt to do this chaining twice.
 173     // e.g if calling 'api.Payment.create' We want to finish creating the order first.
 174     // it would probably be better to have a full whitelist of contributionParams
 175     if (substr($key, 0, 3) === 'api') {
 176       unset($contributionParams[$key]);
 177     }
 178   }
 179
 180   $contribution = civicrm_api3('Contribution', 'create', $contributionParams);
 181   $contribution['values'][$contribution['id']]['line_item'] = array_values($order->getLineItems());
 182
 183   return civicrm_api3_create_success($contribution['values'] ?? [], $params, 'Order', 'create');
 184 }
 185
 186 /**
 187  * Delete a Order.
 188  *
 189  * @param array $params
 190  *   Input parameters.
 191  *
 192  * @return array
 193  * @throws API_Exception
 194  * @throws CiviCRM_API3_Exception
 195  */
 196 function civicrm_api3_order_delete(array $params): array {
 197   $contribution = civicrm_api3('Contribution', 'get', [
 198     'return' => ['is_test'],
 199     'id' => $params['id'],
 200   ]);
 201   if ($contribution['id'] && $contribution['values'][$contribution['id']]['is_test'] == TRUE) {
 202     $result = civicrm_api3('Contribution', 'delete', $params);
 203   }
 204   else {
 205     throw new API_Exception('Only test orders can be deleted.');
 206   }
 207   return civicrm_api3_create_success($result['values'], $params, 'Order', 'delete');
 208 }
 209
 210 /**
 211  * Cancel an Order.
 212  *
 213  * @param array $params
 214  *   Input parameters.
 215  *
 216  * @return array
 217  * @throws \CiviCRM_API3_Exception
 218  */
 219 function civicrm_api3_order_cancel(array $params) {
 220   $contributionStatuses = CRM_Contribute_PseudoConstant::contributionStatus(NULL, 'name');
 221   $params['contribution_status_id'] = array_search('Cancelled', $contributionStatuses);
 222   $result = civicrm_api3('Contribution', 'create', $params);
 223   return civicrm_api3_create_success($result['values'], $params, 'Order', 'cancel');
 224 }
 225
 226 /**
 227  * Adjust Metadata for Cancel action.
 228  *
 229  * The metadata is used for setting defaults, documentation & validation.
 230  *
 231  * @param array $params
 232  *   Array of parameters determined by getfields.
 233  */
 234 function _civicrm_api3_order_cancel_spec(array &$params) {
 235   $params['contribution_id'] = [
 236     'api.required' => 1,
 237     'title' => 'Contribution ID',
 238     'type' => CRM_Utils_Type::T_INT,
 239   ];
 240 }
 241
 242 /**
 243  * Adjust Metadata for Create action.
 244  *
 245  * The metadata is used for setting defaults, documentation & validation.
 246  *
 247  * @param array $params
 248  *   Array of parameters determined by getfields.
 249  */
 250 function _civicrm_api3_order_create_spec(array &$params) {
 251   $params['contact_id'] = [
 252     'name' => 'contact_id',
 253     'title' => 'Contact ID',
 254     'type' => CRM_Utils_Type::T_INT,
 255     'api.required' => TRUE,
 256   ];
 257   $params['total_amount'] = [
 258     'name' => 'total_amount',
 259     'title' => 'Total Amount',
 260   ];
 261   $params['skipCleanMoney'] = [
 262     'api.default' => TRUE,
 263     'title' => 'Do not attempt to convert money values',
 264     'type' => CRM_Utils_Type::T_BOOLEAN,
 265   ];
 266   $params['financial_type_id'] = [
 267     'name' => 'financial_type_id',
 268     'title' => 'Financial Type',
 269     'type' => CRM_Utils_Type::T_INT,
 270     'api.required' => TRUE,
 271     'table_name' => 'civicrm_contribution',
 272     'entity' => 'Contribution',
 273     'bao' => 'CRM_Contribute_BAO_Contribution',
 274     'pseudoconstant' => [
 275       'table' => 'civicrm_financial_type',
 276       'keyColumn' => 'id',
 277       'labelColumn' => 'name',
 278     ],
 279   ];
 280 }
 281
 282 /**
 283  * Adjust Metadata for Delete action.
 284  *
 285  * The metadata is used for setting defaults, documentation & validation.
 286  *
 287  * @param array $params
 288  *   Array of parameters determined by getfields.
 289  */
 290 function _civicrm_api3_order_delete_spec(array &$params) {
 291   $params['contribution_id'] = [
 292     'api.required' => TRUE,
 293     'title' => 'Contribution ID',
 294     'type' => CRM_Utils_Type::T_INT,
 295   ];
 296   $params['id']['api.aliases'] = ['contribution_id'];
 297 }
 298
 299 /**
 300  * Handle possibility of v3 style params.
 301  *
 302  * We used to call v3 Membership.create. Now we call v4.
 303  * This converts membership input parameters.
 304  *
 305  * @param array $membershipParams
 306  *
 307  * @throws \API_Exception
 308  */
 309 function _order_create_wrangle_membership_params(array &$membershipParams) {
 310   $fields = Membership::getFields(FALSE)->execute()->indexBy('name');
 311   // Ensure this legacy parameter is not true.
 312   $membershipParams['skipStatusCal'] = FALSE;
 313   foreach ($fields as $fieldName => $field) {
 314     $customFieldName = 'custom_' . ($field['custom_field_id'] ?? NULL);
 315     if ($field['type'] === ['Custom'] && isset($membershipParams[$customFieldName])) {
 316       $membershipParams[$field['custom_group'] . '.' . $field['custom_field']] = $membershipParams[$customFieldName];
 317       unset($membershipParams[$customFieldName]);
 318     }
 319
 320     if (!empty($membershipParams[$fieldName]) && $field['data_type'] === 'Integer' && !is_numeric($membershipParams[$fieldName])) {
 321       $membershipParams[$field['name'] . ':name'] = $membershipParams[$fieldName];
 322       unset($membershipParams[$field['name']]);
 323     }
 324   }
 325 }