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  */
  28 function civicrm_api3_order_get($params) {
  29   $contributions = [];
  30   $params['api.line_item.get'] = ['qty' => ['<>' => 0]];
  31   $isSequential = FALSE;
  32   if (!empty($params['sequential'])) {
  33     $params['sequential'] = 0;
  34     $isSequential = TRUE;
  35   }
  36   $result = civicrm_api3('Contribution', 'get', $params);
  37   if (!empty($result['values'])) {
  38     foreach ($result['values'] as $key => $contribution) {
  39       $contributions[$key] = $contribution;
  40       $contributions[$key]['line_items'] = $contribution['api.line_item.get']['values'];
  41       unset($contributions[$key]['api.line_item.get']);
  42     }
  43   }
  44   $params['sequential'] = $isSequential;
  45   return civicrm_api3_create_success($contributions, $params, 'Order', 'get');
  46 }
  47
  48 /**
  49  * Adjust Metadata for Get action.
  50  *
  51  * The metadata is used for setting defaults, documentation & validation.
  52  *
  53  * @param array $params
  54  *   Array of parameters determined by getfields.
  55  */
  56 function _civicrm_api3_order_get_spec(&$params) {
  57   $params['id']['api.aliases'] = ['order_id'];
  58   $params['id']['title'] = ts('Contribution / Order ID');
  59 }
  60
  61 /**
  62  * Add or update a Order.
  63  *
  64  * @param array $params
  65  *   Input parameters.
  66  *
  67  * @return array
  68  *   Api result array
  69  *
  70  * @throws \CiviCRM_API3_Exception
  71  * @throws API_Exception
  72  */
  73 function civicrm_api3_order_create($params) {
  74   civicrm_api3_verify_one_mandatory($params, NULL, ['line_items', 'total_amount']);
  75   $entity = NULL;
  76   $entityIds = [];
  77   $params['contribution_status_id'] = $params['contribution_status_id'] ?? 'Pending';
  78   if ($params['contribution_status_id'] !== 'Pending' && 'Pending' !== CRM_Core_PseudoConstant::getName('CRM_Contribute_BAO_Contribution', 'contribution_status_id', $params['contribution_status_id'])) {
  79     CRM_Core_Error::deprecatedFunctionWarning("Creating a Order with a status other than pending is deprecated. Please do not set contribution_status_id, it will default to Pending. You can chain payment creation e.g civicrm_api3('Order', 'create', ['blah' => 'blah', 'contribution_status_id' => 'Pending', 'api.Payment.create => ['total_amount' => 5]]");
  80   }
  81
  82   if (!empty($params['line_items']) && is_array($params['line_items'])) {
  83     $priceSetID = NULL;
  84     CRM_Contribute_BAO_Contribution::checkLineItems($params);
  85     foreach ($params['line_items'] as $lineItems) {
  86       $entityParams = $lineItems['params'] ?? [];
  87       if (!empty($entityParams) && !empty($lineItems['line_item'])) {
  88         $item = reset($lineItems['line_item']);
  89         $entity = str_replace('civicrm_', '', $item['entity_table']);
  90       }
  91
  92       if ($entityParams) {
  93         $supportedEntity = TRUE;
  94         switch ($entity) {
  95           case 'participant':
  96             if (isset($entityParams['participant_status_id'])
  97               && (!CRM_Event_BAO_ParticipantStatusType::getIsValidStatusForClass($entityParams['participant_status_id'], 'Pending'))) {
  98               throw new CiviCRM_API3_Exception('Creating a participant via the Order API with a non "pending" status is not supported');
  99             }
 100             $entityParams['participant_status_id'] = $entityParams['participant_status_id'] ?? 'Pending from incomplete transaction';
 101             $entityParams['status_id'] = $entityParams['participant_status_id'];
 102             break;
 103
 104           case 'membership':
 105             $entityParams['status_id'] = 'Pending';
 106             break;
 107
 108           default:
 109             // Don't create any related entities. We might want to support eg. Pledge one day?
 110             $supportedEntity = FALSE;
 111             break;
 112         }
 113         if ($supportedEntity) {
 114           $entityParams['skipLineItem'] = TRUE;
 115           $entityResult = civicrm_api3($entity, 'create', $entityParams);
 116           $params['contribution_mode'] = $entity;
 117           $entityIds[] = $params[$entity . '_id'] = $entityResult['id'];
 118           foreach ($lineItems['line_item'] as &$items) {
 119             $items['entity_id'] = $entityResult['id'];
 120           }
 121         }
 122       }
 123
 124       if (empty($priceSetID)) {
 125         $item = reset($lineItems['line_item']);
 126         $priceSetID = (int) civicrm_api3('PriceField', 'getvalue', [
 127           'return' => 'price_set_id',
 128           'id' => $item['price_field_id'],
 129         ]);
 130         $params['line_item'][$priceSetID] = [];
 131       }
 132       $params['line_item'][$priceSetID] = array_merge($params['line_item'][$priceSetID], $lineItems['line_item']);
 133     }
 134   }
 135   $contributionParams = $params;
 136   // If this is nested we need to set sequential to 0 as sequential handling is done
 137   // in create_success & id will be miscalculated...
 138   $contributionParams['sequential'] = 0;
 139   foreach ($contributionParams as $key => $value) {
 140     // Unset chained keys so the code does not attempt to do this chaining twice.
 141     // e.g if calling 'api.Payment.create' We want to finish creating the order first.
 142     // it would probably be better to have a full whitelist of contributionParams
 143     if (substr($key, 0, 3) === 'api') {
 144       unset($contributionParams[$key]);
 145     }
 146   }
 147
 148   $contribution = civicrm_api3('Contribution', 'create', $contributionParams);
 149   // add payments
 150   if ($entity && !empty($contribution['id'])) {
 151     foreach ($entityIds as $entityId) {
 152       $paymentParams = [
 153         'contribution_id' => $contribution['id'],
 154         $entity . '_id' => $entityId,
 155       ];
 156       // if entity is pledge then build pledge param
 157       if ($entity == 'pledge') {
 158         $paymentParams += $entityParams;
 159       }
 160       elseif ($entity == 'membership') {
 161         $paymentParams['isSkipLineItem'] = TRUE;
 162       }
 163       civicrm_api3($entity . '_payment', 'create', $paymentParams);
 164     }
 165   }
 166   return civicrm_api3_create_success($contribution['values'] ?? [], $params, 'Order', 'create');
 167 }
 168
 169 /**
 170  * Delete a Order.
 171  *
 172  * @param array $params
 173  *   Input parameters.
 174  * @return array
 175  * @throws API_Exception
 176  * @throws CiviCRM_API3_Exception
 177  */
 178 function civicrm_api3_order_delete($params) {
 179   $contribution = civicrm_api3('Contribution', 'get', [
 180     'return' => ['is_test'],
 181     'id' => $params['id'],
 182   ]);
 183   if ($contribution['id'] && $contribution['values'][$contribution['id']]['is_test'] == TRUE) {
 184     $result = civicrm_api3('Contribution', 'delete', $params);
 185   }
 186   else {
 187     throw new API_Exception('Only test orders can be deleted.');
 188   }
 189   return civicrm_api3_create_success($result['values'], $params, 'Order', 'delete');
 190 }
 191
 192 /**
 193  * Cancel an Order.
 194  *
 195  * @param array $params
 196  *   Input parameters.
 197  *
 198  * @return array
 199  */
 200 function civicrm_api3_order_cancel($params) {
 201   $contributionStatuses = CRM_Contribute_PseudoConstant::contributionStatus(NULL, 'name');
 202   $params['contribution_status_id'] = array_search('Cancelled', $contributionStatuses);
 203   $result = civicrm_api3('Contribution', 'create', $params);
 204   return civicrm_api3_create_success($result['values'], $params, 'Order', 'cancel');
 205 }
 206
 207 /**
 208  * Adjust Metadata for Cancel 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_cancel_spec(&$params) {
 216   $params['contribution_id'] = [
 217     'api.required' => 1,
 218     'title' => 'Contribution ID',
 219     'type' => CRM_Utils_Type::T_INT,
 220   ];
 221 }
 222
 223 /**
 224  * Adjust Metadata for Create action.
 225  *
 226  * The metadata is used for setting defaults, documentation & validation.
 227  *
 228  * @param array $params
 229  *   Array of parameters determined by getfields.
 230  */
 231 function _civicrm_api3_order_create_spec(&$params) {
 232   $params['contact_id'] = [
 233     'name' => 'contact_id',
 234     'title' => 'Contact ID',
 235     'type' => CRM_Utils_Type::T_INT,
 236     'api.required' => TRUE,
 237   ];
 238   $params['total_amount'] = [
 239     'name' => 'total_amount',
 240     'title' => 'Total Amount',
 241   ];
 242   $params['financial_type_id'] = [
 243     'name' => 'financial_type_id',
 244     'title' => 'Financial Type',
 245     'type' => CRM_Utils_Type::T_INT,
 246     'api.required' => TRUE,
 247     'table_name' => 'civicrm_contribution',
 248     'entity' => 'Contribution',
 249     'bao' => 'CRM_Contribute_BAO_Contribution',
 250     'pseudoconstant' => [
 251       'table' => 'civicrm_financial_type',
 252       'keyColumn' => 'id',
 253       'labelColumn' => 'name',
 254     ],
 255   ];
 256 }
 257
 258 /**
 259  * Adjust Metadata for Delete action.
 260  *
 261  * The metadata is used for setting defaults, documentation & validation.
 262  *
 263  * @param array $params
 264  *   Array of parameters determined by getfields.
 265  */
 266 function _civicrm_api3_order_delete_spec(&$params) {
 267   $params['contribution_id'] = [
 268     'api.required' => TRUE,
 269     'title' => 'Contribution ID',
 270     'type' => CRM_Utils_Type::T_INT,
 271   ];
 272   $params['id']['api.aliases'] = ['contribution_id'];
 273 }