Commit | Line | Data |
---|---|---|
6a488035 TO |
1 | <?php |
2 | // $Id$ | |
3 | ||
4 | /* | |
5 | +--------------------------------------------------------------------+ | |
6 | | CiviCRM version 4.3 | | |
7 | +--------------------------------------------------------------------+ | |
8 | | Copyright CiviCRM LLC (c) 2004-2013 | | |
9 | +--------------------------------------------------------------------+ | |
10 | | This file is a part of CiviCRM. | | |
11 | | | | |
12 | | CiviCRM is free software; you can copy, modify, and distribute it | | |
13 | | under the terms of the GNU Affero General Public License | | |
14 | | Version 3, 19 November 2007 and the CiviCRM Licensing Exception. | | |
15 | | | | |
16 | | CiviCRM is distributed in the hope that it will be useful, but | | |
17 | | WITHOUT ANY WARRANTY; without even the implied warranty of | | |
18 | | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. | | |
19 | | See the GNU Affero General Public License for more details. | | |
20 | | | | |
21 | | You should have received a copy of the GNU Affero General Public | | |
22 | | License and the CiviCRM Licensing Exception along | | |
23 | | with this program; if not, contact CiviCRM LLC | | |
24 | | at info[AT]civicrm[DOT]org. If you have questions about the | | |
25 | | GNU Affero General Public License or the licensing of CiviCRM, | | |
26 | | see the CiviCRM license FAQ at http://civicrm.org/licensing | | |
27 | +--------------------------------------------------------------------+ | |
28 | */ | |
29 | ||
30 | /** | |
31 | * File for the CiviCRM APIv3 Contribution functions | |
32 | * | |
33 | * @package CiviCRM_APIv3 | |
34 | * @subpackage API_Contribute | |
35 | * | |
36 | * @copyright CiviCRM LLC (c) 2004-2013 | |
37 | * @version $Id: Contribution.php 30486 2010-11-02 16:12:09Z shot $ | |
38 | * | |
39 | */ | |
40 | ||
41 | /** | |
42 | * Add or update a contribution | |
43 | * | |
44 | * @param array $params (reference ) input parameters | |
45 | * | |
46 | * @return array Api result array | |
47 | * @static void | |
48 | * @access public | |
49 | * @example ContributionCreate.php | |
50 | * {@getfields Contribution_create} | |
51 | */ | |
52 | function civicrm_api3_contribution_create(&$params) { | |
53 | $values = array(); | |
54 | ||
55 | _civicrm_api3_contribute_format_params($params, $values); | |
56 | ||
57 | _civicrm_api3_custom_format_params($params, $values, 'Contribution'); | |
58 | $values["contact_id"] = CRM_Utils_Array::value('contact_id', $params); | |
59 | $values["source"] = CRM_Utils_Array::value('source', $params); | |
502b3d42 | 60 | //legacy soft credit handling |
61 | if(!empty($params['soft_credit_to'])){ | |
62 | $values['soft_credit'] = array(array( | |
63 | 'contact_id' => $params['soft_credit_to'], | |
64 | 'amount' => $params['total_amount'])); | |
65 | } | |
6a488035 TO |
66 | $ids = array(); |
67 | if (CRM_Utils_Array::value('id', $params)) { | |
68 | $ids['contribution'] = $params['id']; | |
69 | } | |
6a488035 TO |
70 | $contribution = CRM_Contribute_BAO_Contribution::create($values, $ids); |
71 | ||
72 | if (is_a($contribution, 'CRM_Core_Error')) { | |
73 | return civicrm_api3_create_error($contribution->_errors[0]['message']); | |
74 | } | |
75 | _civicrm_api3_object_to_array($contribution, $contributeArray[$contribution->id]); | |
76 | ||
77 | return civicrm_api3_create_success($contributeArray, $params, 'contribution', 'create', $contribution); | |
78 | } | |
11e09c59 TO |
79 | |
80 | /** | |
6a488035 TO |
81 | * Adjust Metadata for Create action |
82 | * | |
83 | * The metadata is used for setting defaults, documentation & validation | |
84 | * @param array $params array or parameters determined by getfields | |
85 | */ | |
86 | function _civicrm_api3_contribution_create_spec(&$params) { | |
87 | $params['contact_id']['api.required'] = 1; | |
88 | $params['total_amount']['api.required'] = 1; | |
89 | $params['payment_processor'] = array( | |
90 | 'name' => 'payment_processor', | |
91 | 'title' => 'Payment Processor ID', | |
92 | 'description' => 'ID of payment processor used for this contribution', | |
93 | // field is called payment processor - not payment processor id but can only be one id so | |
94 | // it seems likely someone will fix it up one day to be more consistent - lets alias it from the start | |
95 | 'api.aliases' => array('payment_processor_id'), | |
96 | ); | |
97 | $params['financial_type_id']['api.aliases'] = array('contribution_type_id', 'contribution_type'); | |
98 | $params['financial_type_id']['api.required'] = 1; | |
99 | $params['note'] = array( | |
100 | 'name' => 'note', | |
101 | 'uniqueName' => 'contribution_note', | |
102 | 'title' => 'note', | |
103 | 'type' => 2, | |
104 | 'description' => 'Associated Note in the notes table', | |
105 | ); | |
106 | $params['soft_credit_to'] = array( | |
107 | 'name' => 'soft_credit_to', | |
108 | 'title' => 'Soft Credit contact ID', | |
109 | 'type' => 1, | |
110 | 'description' => 'ID of Contact to be Soft credited to', | |
111 | 'FKClassName' => 'CRM_Contact_DAO_Contact', | |
112 | ); | |
113 | // note this is a recommended option but not adding as a default to avoid | |
114 | // creating unecessary changes for the dev | |
115 | $params['skipRecentView'] = array( | |
116 | 'name' => 'skipRecentView', | |
117 | 'title' => 'Skip adding to recent view', | |
118 | 'type' => 1, | |
119 | 'description' => 'Do not add to recent view (setting this improves performance)', | |
120 | ); | |
121 | $params['skipLineItem'] = array( | |
122 | 'name' => 'skipLineItem', | |
123 | 'title' => 'Skip adding line items', | |
124 | 'type' => 1, | |
125 | 'api.default' => 0, | |
126 | 'description' => 'Do not add line items by default (if you wish to add your own)', | |
127 | ); | |
128 | } | |
129 | ||
130 | /** | |
131 | * Delete a contribution | |
132 | * | |
133 | * @param array $params (reference ) input parameters | |
134 | * | |
135 | * @return boolean true if success, else false | |
136 | * @static void | |
137 | * @access public | |
138 | * {@getfields Contribution_delete} | |
139 | * @example ContributionDelete.php | |
140 | */ | |
141 | function civicrm_api3_contribution_delete($params) { | |
142 | ||
143 | $contributionID = CRM_Utils_Array::value('contribution_id', $params) ? $params['contribution_id'] : $params['id']; | |
144 | if (CRM_Contribute_BAO_Contribution::deleteContribution($contributionID)) { | |
145 | return civicrm_api3_create_success(array($contributionID => 1)); | |
146 | } | |
147 | else { | |
148 | return civicrm_api3_create_error('Could not delete contribution'); | |
149 | } | |
150 | } | |
11e09c59 TO |
151 | |
152 | /** | |
6a488035 TO |
153 | * modify metadata. Legacy support for contribution_id |
154 | */ | |
155 | function _civicrm_api3_contribution_delete_spec(&$params) { | |
156 | $params['id']['api.aliases'] = array('contribution_id'); | |
157 | } | |
158 | ||
159 | /** | |
160 | * Retrieve a set of contributions, given a set of input params | |
161 | * | |
162 | * @param array $params (reference ) input parameters | |
163 | * @param array $returnProperties Which properties should be included in the | |
164 | * returned Contribution object. If NULL, the default | |
165 | * set of properties will be included. | |
166 | * | |
167 | * @return array (reference ) array of contributions, if error an array with an error id and error message | |
168 | * @static void | |
169 | * @access public | |
170 | * {@getfields Contribution_get} | |
171 | * @example ContributionGet.php | |
172 | */ | |
173 | function civicrm_api3_contribution_get($params) { | |
174 | ||
175 | $options = _civicrm_api3_get_options_from_params($params, TRUE,'contribution','get'); | |
176 | $sort = CRM_Utils_Array::value('sort', $options, NULL); | |
177 | $offset = CRM_Utils_Array::value('offset', $options); | |
178 | $rowCount = CRM_Utils_Array::value('limit', $options); | |
179 | $smartGroupCache = CRM_Utils_Array::value('smartGroupCache', $params); | |
180 | $inputParams = CRM_Utils_Array::value('input_params', $options, array()); | |
181 | $returnProperties = CRM_Utils_Array::value('return', $options, NULL); | |
6a488035 TO |
182 | if (empty($returnProperties)) { |
183 | $returnProperties = CRM_Contribute_BAO_Query::defaultReturnProperties(CRM_Contact_BAO_Query::MODE_CONTRIBUTE); | |
184 | } | |
185 | ||
186 | $newParams = CRM_Contact_BAO_Query::convertFormValues($inputParams); | |
187 | $query = new CRM_Contact_BAO_Query($newParams, $returnProperties, NULL, | |
188 | FALSE, FALSE, CRM_Contact_BAO_Query::MODE_CONTRIBUTE | |
189 | ); | |
190 | list($select, $from, $where, $having) = $query->query(); | |
191 | ||
192 | $sql = "$select $from $where $having"; | |
193 | ||
194 | if (!empty($sort)) { | |
195 | $sql .= " ORDER BY $sort "; | |
196 | } | |
197 | $sql .= " LIMIT $offset, $rowCount "; | |
198 | $dao = CRM_Core_DAO::executeQuery($sql); | |
199 | ||
200 | $contribution = array(); | |
201 | while ($dao->fetch()) { | |
202 | //CRM-8662 | |
76ca3345 KJ |
203 | $contribution_details = $query->store($dao); |
204 | $softContribution = CRM_Contribute_BAO_ContributionSoft::getSoftContribution($dao->contribution_id , TRUE); | |
205 | $contribution[$dao->contribution_id] = array_merge($contribution_details, $softContribution); | |
a1c68fd2 | 206 | if(isset($contribution[$dao->contribution_id]['financial_type_id'])){ |
207 | $contribution[$dao->contribution_id]['financial_type_id'] = $contribution[$dao->contribution_id]['financial_type_id']; | |
208 | } | |
76ca3345 KJ |
209 | // format soft credit for backward compatibility |
210 | _civicrm_api3_format_soft_credit($contribution[$dao->contribution_id]); | |
6a488035 TO |
211 | } |
212 | return civicrm_api3_create_success($contribution, $params, 'contribution', 'get', $dao); | |
213 | } | |
11e09c59 | 214 | |
76ca3345 KJ |
215 | /** |
216 | * This function is used to format the soft credit for backward compatibility | |
217 | * as of v4.4 we support multiple soft credit, so now contribution returns array with 'soft_credit' as key | |
218 | * but we still return first soft credit as a part of contribution array | |
219 | */ | |
220 | function _civicrm_api3_format_soft_credit(&$contribution) { | |
221 | if (!empty($contribution['soft_credit'])) { | |
222 | $contribution['soft_credit_to'] = $contribution['soft_credit'][1]['contact_id']; | |
223 | $contribution['soft_credit_id'] = $contribution['soft_credit'][1]['soft_credit_id']; | |
224 | } | |
225 | } | |
226 | ||
11e09c59 | 227 | /** |
6a488035 TO |
228 | * Adjust Metadata for Get action |
229 | * | |
230 | * The metadata is used for setting defaults, documentation & validation | |
231 | * @param array $params array or parameters determined by getfields | |
232 | */ | |
233 | function _civicrm_api3_contribution_get_spec(&$params) { | |
234 | $params['contribution_test']['api.default'] = 0; | |
235 | $params['financial_type_id']['api.aliases'] = array('contribution_type_id'); | |
236 | $params['contact_id'] = $params['contribution_contact_id']; | |
237 | $params['contact_id']['api.aliases'] = array('contribution_contact_id'); | |
238 | unset($params['contribution_contact_id']); | |
239 | } | |
240 | ||
241 | /** | |
242 | * take the input parameter list as specified in the data model and | |
243 | * convert it into the same format that we use in QF and BAO object | |
244 | * | |
245 | * @param array $params Associative array of property name/value | |
246 | * pairs to insert in new contact. | |
247 | * @param array $values The reformatted properties that we can use internally | |
248 | * ' | |
249 | * | |
250 | * @return array|CRM_Error | |
251 | * @access public | |
252 | */ | |
253 | function _civicrm_api3_contribute_format_params($params, &$values, $create = FALSE) { | |
254 | //legacy way of formatting from v2 api - v3 way is to define metadata & do it in the api layer | |
255 | require_once 'api/v3/utils.php'; | |
256 | _civicrm_api3_filter_fields_for_bao('Contribution', $params, $values); | |
257 | ||
258 | foreach ($params as $key => $value) { | |
259 | // ignore empty values or empty arrays etc | |
260 | if (CRM_Utils_System::isNull($value)) { | |
261 | continue; | |
262 | } | |
263 | // note that this is legacy handling - these should be handled at the api layer | |
264 | switch ($key) { | |
265 | case 'financial_type' :// should be dealt with either api pseudoconstant in validate_integer fn | |
266 | $contributionTypeId = CRM_Utils_Array::key ( ucfirst ( $value ), CRM_Contribute_PseudoConstant::financialType() ); | |
267 | if ($contributionTypeId) { | |
268 | if (CRM_Utils_Array::value('financial_type_id', $values) && $contributionTypeId != $values['financial_type_id']) { | |
269 | throw new Exception("Mismatched Financial Type and Financial Type Id"); | |
270 | } | |
271 | $values ['financial_type_id'] = $contributionTypeId; | |
272 | } | |
273 | else { | |
274 | throw new Exception("Invalid Financial Type"); | |
275 | } | |
276 | break; | |
277 | ||
6a488035 TO |
278 | default: |
279 | break; | |
280 | } | |
281 | } | |
282 | ||
283 | return array(); | |
284 | } | |
285 | ||
286 | /** | |
287 | * Process a transaction and record it against the contact. | |
288 | * | |
289 | * @param array $params (reference ) input parameters | |
290 | * | |
291 | * @return array (reference ) contribution of created or updated record (or a civicrm error) | |
292 | * @static void | |
293 | * @access public | |
294 | * | |
295 | */ | |
296 | function civicrm_api3_contribution_transact($params) { | |
297 | $required = array('amount'); | |
298 | foreach ($required as $key) { | |
299 | if (!isset($params[$key])) { | |
300 | return civicrm_api3_create_error("Missing parameter $key: civicrm_contribute_transact() requires a parameter '$key'."); | |
301 | } | |
302 | } | |
303 | ||
304 | // allow people to omit some values for convenience | |
305 | // 'payment_processor_id' => NULL /* we could retrieve the default processor here, but only if it's missing to avoid an extra lookup */ | |
306 | $defaults = array( | |
307 | 'payment_processor_mode' => 'live', | |
308 | ); | |
309 | $params = array_merge($defaults, $params); | |
310 | ||
311 | // clean up / adjust some values which | |
312 | if (!isset($params['total_amount'])) { | |
313 | $params['total_amount'] = $params['amount']; | |
314 | } | |
315 | if (!isset($params['net_amount'])) { | |
316 | $params['net_amount'] = $params['amount']; | |
317 | } | |
318 | if (!isset($params['receive_date'])) { | |
319 | $params['receive_date'] = date('Y-m-d'); | |
320 | } | |
321 | if (!isset($params['invoiceID']) && isset($params['invoice_id'])) { | |
322 | $params['invoiceID'] = $params['invoice_id']; | |
323 | } | |
324 | ||
6a488035 TO |
325 | $paymentProcessor = CRM_Financial_BAO_PaymentProcessor::getPayment($params['payment_processor_id'], $params['payment_processor_mode']); |
326 | if (civicrm_error($paymentProcessor)) { | |
327 | return $paymentProcessor; | |
328 | } | |
329 | ||
6a488035 TO |
330 | $payment = &CRM_Core_Payment::singleton($params['payment_processor_mode'], $paymentProcessor); |
331 | if (civicrm_error($payment)) { | |
332 | return $payment; | |
333 | } | |
334 | ||
335 | $transaction = $payment->doDirectPayment($params); | |
336 | if (civicrm_error($transaction)) { | |
337 | return $transaction; | |
338 | } | |
339 | ||
340 | // but actually, $payment->doDirectPayment() doesn't return a | |
341 | // CRM_Core_Error by itself | |
342 | if (get_class($transaction) == 'CRM_Core_Error') { | |
343 | $errs = $transaction->getErrors(); | |
344 | if (!empty($errs)) { | |
345 | $last_error = array_shift($errs); | |
346 | return CRM_Core_Error::createApiError($last_error['message']); | |
347 | } | |
348 | } | |
349 | ||
350 | $contribution = civicrm_api('contribution', 'create', $params); | |
351 | return $contribution['values']; | |
352 | } | |
353 | /** | |
354 | * Send a contribution confirmation (receipt or invoice) | |
355 | * The appropriate online template will be used (the existence of related objects | |
356 | * (e.g. memberships ) will affect this selection | |
357 | * @param array $params input parameters | |
358 | * {@getfields Contribution_sendconfirmation} | |
359 | * @return array Api result array | |
360 | * @static void | |
361 | * @access public | |
362 | * | |
363 | */ | |
364 | function civicrm_api3_contribution_sendconfirmation($params) { | |
365 | $contribution = new CRM_Contribute_BAO_Contribution(); | |
366 | $contribution->id = $params['id']; | |
76ca3345 | 367 | if (! $contribution->find(TRUE)) { |
6a488035 TO |
368 | throw new Exception('Contribution does not exist'); |
369 | } | |
370 | $input = $ids = $cvalues = array('receipt_from_email' => $params['receipt_from_email']); | |
76ca3345 KJ |
371 | $contribution->loadRelatedObjects($input, $ids, FALSE, TRUE); |
372 | $contribution->composeMessageArray($input, $ids, $cvalues, FALSE, FALSE); | |
6a488035 TO |
373 | } |
374 | ||
11e09c59 | 375 | /** |
6a488035 TO |
376 | * Adjust Metadata for Create action |
377 | * | |
378 | * The metadata is used for setting defaults, documentation & validation | |
379 | * @param array $params array or parameters determined by getfields | |
380 | */ | |
381 | function _civicrm_api3_contribution_sendconfirmation_spec(&$params) { | |
382 | $params['id'] = array( | |
383 | 'api.required' => 1, | |
384 | 'title' => 'Contribution ID' | |
385 | ); | |
386 | $params['receipt_from_email'] = array( | |
387 | 'api.required' =>1, | |
388 | 'title' => 'From Email (required until someone provides a patch :-)', | |
389 | ||
390 | ); | |
391 | } |