api/v3/LineItem.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 /**
  14  * This api exposes CiviCRM LineItem records.
  15  *
  16  * Line items are sub-components of a complete financial transaction record.
  17  *
  18  * @package CiviCRM_APIv3
  19  */
  20
  21 /**
  22  * Create or update a line_item.
  23  *
  24  * @param array $params
  25  *   Array of property name/value pairs to insert in new 'line_item'
  26  *
  27  * @return array
  28  *   api result array
  29  */
  30 function civicrm_api3_line_item_create($params) {
  31   // @todo the following line is not really appropriate for the api. The BAO should
  32   // do the work, and it should be in a tighter function. The below function is  not really
  33   // readable because it is handling contribution and line item together.
  34   $params = CRM_Contribute_BAO_Contribution::checkTaxAmount($params, TRUE);
  35   return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params, 'LineItem');
  36 }
  37
  38 /**
  39  * Adjust Metadata for Create action.
  40  *
  41  * The metadata is used for setting defaults, documentation & validation.
  42  *
  43  * @param array $params
  44  *   Array of parameters determined by getfields.
  45  */
  46 function _civicrm_api3_line_item_create_spec(&$params) {
  47   $params['entity_id']['api.required'] = 1;
  48   $params['qty']['api.required'] = 1;
  49   $params['unit_price']['api.required'] = 1;
  50   $params['line_total']['api.required'] = 1;
  51   $params['label']['api.default'] = 'line item';
  52 }
  53
  54 /**
  55  * Returns array of line_items  matching a set of one or more group properties.
  56  *
  57  * @param array $params
  58  *   Array of one or more valid property_name=>value pairs. If $params is set.
  59  *   as null, all line_items will be returned (default limit is 25)
  60  *
  61  * @return array
  62  *   Array of matching line_items
  63  */
  64 function civicrm_api3_line_item_get($params) {
  65   if (CRM_Financial_BAO_FinancialType::isACLFinancialTypeStatus() && !empty($params['check_permissions'])) {
  66     CRM_Price_BAO_LineItem::getAPILineItemParams($params);
  67   }
  68   return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params);
  69 }
  70
  71 /**
  72  * Delete an existing LineItem.
  73  *
  74  * This method is used to delete any existing LineItem given its id.
  75  *
  76  * @param array $params
  77  *   Array containing id of the group to be deleted.
  78  * @return array API result array
  79  * @throws API_Exception
  80  */
  81 function civicrm_api3_line_item_delete($params) {
  82   if (CRM_Financial_BAO_FinancialType::isACLFinancialTypeStatus() && !empty($params['check_permissions'])) {
  83     CRM_Financial_BAO_FinancialType::getAvailableFinancialTypes($types, CRM_Core_Action::DELETE);
  84     if (empty($params['financial_type_id'])) {
  85       $params['financial_type_id'] = CRM_Core_DAO::getFieldValue('CRM_Price_DAO_LineItem', $params['id'], 'financial_type_id');
  86     }
  87     if (!in_array($params['financial_type_id'], array_keys($types))) {
  88       throw new API_Exception('You do not have permission to delete this line item');
  89     }
  90   }
  91   return _civicrm_api3_basic_delete(_civicrm_api3_get_BAO(__FUNCTION__), $params);
  92 }