api/v3/Pledge.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 Pledge.
  14  *
  15  * @package CiviCRM_APIv3
  16  */
  17
  18 /**
  19  * Create or updates an Pledge.
  20  *
  21  * @param array $params
  22  *
  23  * @return array
  24  *   Array containing 'is_error' to denote success or failure and details of the created pledge
  25  * @throws \API_Exception
  26  */
  27 function civicrm_api3_pledge_create($params) {
  28   _civicrm_api3_pledge_format_params($params, TRUE);
  29   return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params, 'Pledge');
  30 }
  31
  32 /**
  33  * Delete a pledge.
  34  *
  35  * @param array $params
  36  *   Array included 'pledge_id' of pledge to delete.
  37  *
  38  * @return array
  39  */
  40 function civicrm_api3_pledge_delete($params) {
  41   if (CRM_Pledge_BAO_Pledge::deletePledge($params['id'])) {
  42     return civicrm_api3_create_success([
  43       'id' => $params['id'],
  44     ], $params, 'Pledge', 'delete');
  45   }
  46   else {
  47     return civicrm_api3_create_error('Could not delete pledge');
  48   }
  49 }
  50
  51 /**
  52  * Adjust metadata for pledge delete action.
  53  *
  54  * @param array $params
  55  */
  56 function _civicrm_api3_pledge_delete_spec(&$params) {
  57   // set as not required as pledge_id also acceptable & no either/or std yet
  58   $params['id']['api.aliases'] = ['pledge_id'];
  59 }
  60
  61 /**
  62  * Adjust field specification specific to get requests.
  63  *
  64  * @param array $params
  65  */
  66 function _civicrm_api3_pledge_get_spec(&$params) {
  67   $params['next_pay_date'] = [
  68     'name' => 'next_pay_date',
  69     'type' => 12,
  70     'title' => 'Pledge Made',
  71     'api.filter' => 0,
  72     'api.return' => 1,
  73   ];
  74   $params['pledge_is_test']['api.default'] = 0;
  75   $params['pledge_financial_type_id']['api.aliases'] = ['contribution_type_id', 'contribution_type'];
  76
  77 }
  78
  79 /**
  80  * Adjust field specification specific to get requests.
  81  *
  82  * @param array $params
  83  */
  84 function _civicrm_api3_pledge_create_spec(&$params) {
  85
  86   $required = ['contact_id', 'amount', 'installments', 'start_date', 'financial_type_id'];
  87   foreach ($required as $required_field) {
  88     $params[$required_field]['api.required'] = 1;
  89   }
  90   // @todo this can come from xml
  91   $params['amount']['api.aliases'] = ['pledge_amount'];
  92   $params['financial_type_id']['api.aliases'] = ['contribution_type_id', 'contribution_type'];
  93 }
  94
  95 /**
  96  * Retrieve a set of pledges, given a set of input params.
  97  *
  98  * @param array $params
  99  *   Input parameters. Use interrogate for possible fields.
 100  *
 101  * @return array
 102  *   array of pledges, if error an array with an error id and error message
 103  */
 104 function civicrm_api3_pledge_get($params) {
 105   $mode = CRM_Contact_BAO_Query::MODE_PLEDGE;
 106
 107   list($dao, $query) = _civicrm_api3_get_query_object($params, $mode, 'Pledge');
 108
 109   $pledge = [];
 110   while ($dao->fetch()) {
 111     $pledge[$dao->pledge_id] = $query->store($dao);
 112   }
 113
 114   return civicrm_api3_create_success($pledge, $params, 'Pledge', 'get', $dao);
 115 }
 116
 117 /**
 118  * Set default to not return test params.
 119  */
 120 function _civicrm_api3_pledge_get_defaults() {
 121   return ['pledge_test' => 0];
 122 }
 123
 124 /**
 125  * Legacy function to format pledge parameters.
 126  *
 127  * I removed a bunch of stuff no longer required from here but it still needs
 128  * more culling
 129  * take the input parameter list as specified in the data model and
 130  * convert it into the same format that we use in QF and BAO object
 131  *
 132  * @param array $values
 133  *   The reformatted properties that we can use internally.
 134  */
 135 function _civicrm_api3_pledge_format_params(&$values) {
 136
 137   // probably most of the below can be removed.... just needs a little more review
 138   if (array_key_exists('original_installment_amount', $values)) {
 139     $values['installment_amount'] = $values['original_installment_amount'];
 140     //it seems it will only create correctly with BOTH installment amount AND pledge_installment_amount set
 141     //pledge installment amount required for pledge payments
 142     $values['pledge_original_installment_amount'] = $values['original_installment_amount'];
 143   }
 144
 145   if (array_key_exists('pledge_original_installment_amount', $values)) {
 146     $values['installment_amount'] = $values['pledge_original_installment_amount'];
 147   }
 148
 149   if (empty($values['id'])) {
 150     //at this point both should be the same so unset both if not set - passing in empty
 151     //value causes crash rather creating new - do it before next section as null values ignored in 'switch'
 152     unset($values['id']);
 153
 154     //if you have a single installment when creating & you don't set the pledge status (not a required field) then
 155     //status id is left null for pledge payments in BAO
 156     // so we are hacking in the addition of the pledge_status_id to pending here
 157     if (empty($values['status_id']) && $values['installments'] == 1) {
 158       $contributionStatus = CRM_Contribute_PseudoConstant::contributionStatus(NULL, 'name');
 159       $values['status_id'] = array_search('Pending', $contributionStatus);
 160     }
 161   }
 162   if (empty($values['scheduled_date']) && array_key_exists('start_date', $values)) {
 163     $values['scheduled_date'] = $values['start_date'];
 164   }
 165 }