/**
* Get an existing contribution.
*
* Returns a single existing Contribution object which matches ALL property
* values passed in $params. An error object is returned if there is
* no match, or more than one match. This API can be used to retrieve
* the CRM internal identifier (contribution_id) based on a unique property.
* It can also be used to retrieve any desired
* contribution properties based on a known contribution_id.
*
* @param array $params Associative array of property name/value
* pairs to attempt to match on.
* @param array $returnProperties Which properties should be included in the
* returned Contribution object. If NULL, the default
* set of properties will be included.
*
* @return CRM_Contribution|CRM_Core_Error Return the Contribution Object if found, else
* Error Object
*
* @access public
*
*/
function &crm_get_contribution($params, $returnProperties = null)
{
_crm_initialize();
// empty parameters ?
if (empty($params)) {
return _crm_error('$params is empty');
}
// correct parameter format ?
if (!is_array($params)) {
return _crm_error('$params is not an array');
}
if (!CRM_Utils_Array::value('contribution_id', $params)) {
$returnProperties = array('trxn_id');
$contributions = crm_contribution_search($params, $returnProperties);
if (count($contributions) != 1) {
return _crm_error(count($contributions) . " contributions matching input params.");
}
$contributionIds = array_keys($contributions);
$params['contribution_id'] = $contributionIds[0];
}
$params['id'] = $params['contribution_id'];
$ids = array();
$contribution =& CRM_Contribute_BAO_Contribution::getValues($params, $defaults, $ids);
if ($contribution == null || is_a($contribution, 'CRM_Core_Error') || !$contribution->id) {
return _crm_error('Did not find contribution object for ' . $params['contribution_id']);
}
unset($params['id']);
$contribution->contribution_type_object = CRM_Contribute_BAO_Contribution::getValues($params, $defaults, $ids);
$contribution->custom_values =& CRM_Core_BAO_CustomValue::getContributionValues($contribution->id);
return $contribution;
}
