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   $entity = NULL;
  77   $entityIds = [];
  78   $params['contribution_status_id'] = 'Pending';
  79   $priceSetID = 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 $lineItems) {
  84       $entityParams = $lineItems['params'] ?? [];
  85       if (!empty($entityParams) && !empty($lineItems['line_item'])) {
  86         $item = reset($lineItems['line_item']);
  87         if (!empty($item['membership_type_id'])) {
  88           $entity = 'membership';
  89         }
  90         else {
  91           $entity = str_replace('civicrm_', '', $item['entity_table']);
  92         }
  93       }
  94
  95       if ($entityParams) {
  96         $supportedEntity = TRUE;
  97         switch ($entity) {
  98           case 'participant':
  99             if (isset($entityParams['participant_status_id'])
 100               && (!CRM_Event_BAO_ParticipantStatusType::getIsValidStatusForClass($entityParams['participant_status_id'], 'Pending'))) {
 101               throw new CiviCRM_API3_Exception('Creating a participant via the Order API with a non "pending" status is not supported');
 102             }
 103             $entityParams['participant_status_id'] = $entityParams['participant_status_id'] ?? 'Pending from incomplete transaction';
 104             $entityParams['status_id'] = $entityParams['participant_status_id'];
 105             break;
 106
 107           case 'membership':
 108             $entityParams['status_id'] = 'Pending';
 109             break;
 110
 111           default:
 112             // Don't create any related entities. We might want to support eg. Pledge one day?
 113             $supportedEntity = FALSE;
 114             break;
 115         }
 116         if ($supportedEntity) {
 117           $entityParams['skipLineItem'] = TRUE;
 118           $entityResult = civicrm_api3($entity, 'create', $entityParams);
 119           $params['contribution_mode'] = $entity;
 120           $entityIds[] = $params[$entity . '_id'] = $entityResult['id'];
 121           foreach ($lineItems['line_item'] as &$items) {
 122             $items['entity_id'] = $entityResult['id'];
 123           }
 124         }
 125       }
 126
 127       if (empty($priceSetID)) {
 128         $item = reset($lineItems['line_item']);
 129         $priceSetID = (int) civicrm_api3('PriceField', 'getvalue', [
 130           'return' => 'price_set_id',
 131           'id' => $item['price_field_id'],
 132         ]);
 133         $params['line_item'][$priceSetID] = [];
 134       }
 135       $params['line_item'][$priceSetID] = array_merge($params['line_item'][$priceSetID], $lineItems['line_item']);
 136     }
 137   }
 138   $contributionParams = $params;
 139   // If this is nested we need to set sequential to 0 as sequential handling is done
 140   // in create_success & id will be miscalculated...
 141   $contributionParams['sequential'] = 0;
 142   foreach ($contributionParams as $key => $value) {
 143     // Unset chained keys so the code does not attempt to do this chaining twice.
 144     // e.g if calling 'api.Payment.create' We want to finish creating the order first.
 145     // it would probably be better to have a full whitelist of contributionParams
 146     if (substr($key, 0, 3) === 'api') {
 147       unset($contributionParams[$key]);
 148     }
 149   }
 150
 151   $contribution = civicrm_api3('Contribution', 'create', $contributionParams);
 152   $contribution['values'][$contribution['id']]['line_item'] = $params['line_item'][$priceSetID] ?? [];
 153
 154   // add payments
 155   if ($entity && !empty($contribution['id'])) {
 156     foreach ($entityIds as $entityId) {
 157       $paymentParams = [
 158         'contribution_id' => $contribution['id'],
 159         $entity . '_id' => $entityId,
 160       ];
 161       // if entity is pledge then build pledge param
 162       if ($entity === 'pledge') {
 163         $paymentParams += $entityParams;
 164       }
 165       elseif ($entity === 'membership') {
 166         $paymentParams['isSkipLineItem'] = TRUE;
 167       }
 168       civicrm_api3($entity . '_payment', 'create', $paymentParams);
 169     }
 170   }
 171   return civicrm_api3_create_success($contribution['values'] ?? [], $params, 'Order', 'create');
 172 }
 173
 174 /**
 175  * Delete a Order.
 176  *
 177  * @param array $params
 178  *   Input parameters.
 179  *
 180  * @return array
 181  * @throws API_Exception
 182  * @throws CiviCRM_API3_Exception
 183  */
 184 function civicrm_api3_order_delete(array $params): array {
 185   $contribution = civicrm_api3('Contribution', 'get', [
 186     'return' => ['is_test'],
 187     'id' => $params['id'],
 188   ]);
 189   if ($contribution['id'] && $contribution['values'][$contribution['id']]['is_test'] == TRUE) {
 190     $result = civicrm_api3('Contribution', 'delete', $params);
 191   }
 192   else {
 193     throw new API_Exception('Only test orders can be deleted.');
 194   }
 195   return civicrm_api3_create_success($result['values'], $params, 'Order', 'delete');
 196 }
 197
 198 /**
 199  * Cancel an Order.
 200  *
 201  * @param array $params
 202  *   Input parameters.
 203  *
 204  * @return array
 205  * @throws \CiviCRM_API3_Exception
 206  */
 207 function civicrm_api3_order_cancel(array $params) {
 208   $contributionStatuses = CRM_Contribute_PseudoConstant::contributionStatus(NULL, 'name');
 209   $params['contribution_status_id'] = array_search('Cancelled', $contributionStatuses);
 210   $result = civicrm_api3('Contribution', 'create', $params);
 211   return civicrm_api3_create_success($result['values'], $params, 'Order', 'cancel');
 212 }
 213
 214 /**
 215  * Adjust Metadata for Cancel action.
 216  *
 217  * The metadata is used for setting defaults, documentation & validation.
 218  *
 219  * @param array $params
 220  *   Array of parameters determined by getfields.
 221  */
 222 function _civicrm_api3_order_cancel_spec(array &$params) {
 223   $params['contribution_id'] = [
 224     'api.required' => 1,
 225     'title' => 'Contribution ID',
 226     'type' => CRM_Utils_Type::T_INT,
 227   ];
 228 }
 229
 230 /**
 231  * Adjust Metadata for Create action.
 232  *
 233  * The metadata is used for setting defaults, documentation & validation.
 234  *
 235  * @param array $params
 236  *   Array of parameters determined by getfields.
 237  */
 238 function _civicrm_api3_order_create_spec(array &$params) {
 239   $params['contact_id'] = [
 240     'name' => 'contact_id',
 241     'title' => 'Contact ID',
 242     'type' => CRM_Utils_Type::T_INT,
 243     'api.required' => TRUE,
 244   ];
 245   $params['total_amount'] = [
 246     'name' => 'total_amount',
 247     'title' => 'Total Amount',
 248   ];
 249   $params['skipCleanMoney'] = [
 250     'api.default' => TRUE,
 251     'title' => 'Do not attempt to convert money values',
 252     'type' => CRM_Utils_Type::T_BOOLEAN,
 253   ];
 254   $params['financial_type_id'] = [
 255     'name' => 'financial_type_id',
 256     'title' => 'Financial Type',
 257     'type' => CRM_Utils_Type::T_INT,
 258     'api.required' => TRUE,
 259     'table_name' => 'civicrm_contribution',
 260     'entity' => 'Contribution',
 261     'bao' => 'CRM_Contribute_BAO_Contribution',
 262     'pseudoconstant' => [
 263       'table' => 'civicrm_financial_type',
 264       'keyColumn' => 'id',
 265       'labelColumn' => 'name',
 266     ],
 267   ];
 268 }
 269
 270 /**
 271  * Adjust Metadata for Delete action.
 272  *
 273  * The metadata is used for setting defaults, documentation & validation.
 274  *
 275  * @param array $params
 276  *   Array of parameters determined by getfields.
 277  */
 278 function _civicrm_api3_order_delete_spec(array &$params) {
 279   $params['contribution_id'] = [
 280     'api.required' => TRUE,
 281     'title' => 'Contribution ID',
 282     'type' => CRM_Utils_Type::T_INT,
 283   ];
 284   $params['id']['api.aliases'] = ['contribution_id'];
 285 }