From c5884dfddb30e40e06af9ef0f2dc940ad6ae55bd Mon Sep 17 00:00:00 2001 From: eileen Date: Mon, 21 Oct 2019 15:13:52 +1300 Subject: [PATCH] Add a bunch of additional getters & setters --- CRM/Core/Payment.php | 371 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 355 insertions(+), 16 deletions(-) diff --git a/CRM/Core/Payment.php b/CRM/Core/Payment.php index cb2e2f77cf..089dffc822 100644 --- a/CRM/Core/Payment.php +++ b/CRM/Core/Payment.php @@ -81,7 +81,7 @@ abstract class CRM_Core_Payment { RECURRING_PAYMENT_END = 'END'; /** - * @var object + * @var array */ protected $_paymentProcessor; @@ -156,6 +156,125 @@ abstract class CRM_Core_Payment { */ protected $contributionID; + /** + * Contact ID for payment. + * + * @var int + */ + protected $contactID; + + /** + * Recurring contribution that is being paid. + * + * @var int + */ + protected $contributionRecurID; + + /** + * Description of purchase. + * + * @var string + */ + protected $description; + + /** + * CiviCRM generated Invoice ID. + * + * @var string + */ + protected $invoiceID; + + /** + * Is this a recurring contribution. + * + * @var bool + */ + protected $isRecur; + + /** + * Payment processor generated string for charging. + * + * A payment token could be a single use token (e.g generated by + * a client side script) or a token that permits recurring or on demand charging. + * + * The key thing is it is passed to the processor in lieu of card details to + * initiate a payment. + * + * Generally if a processor is going to pass in a payment token generated through + * javascript it would add 'payment_token' to the array it returns in it's + * implementation of getPaymentFormFields. This will add a hidden 'payment_token' field to + * the form. A good example is client side encryption where credit card details are replaced by + * an encrypted token using a gateway provided javascript script. In this case the javascript will + * remove the credit card details from the form before submitting and populate the payment_token field. + * + * A more complex example is used by paypal checkout where the payment token is generated + * via a pre-approval process. In that case the doPreApproval function is called on the processor + * class to get information to then interact with paypal via js, finally getting a payment token. + * (at this stage the pre-approve api is not in core but that is likely to change - we just need + * to think about the permissions since we don't want to expose to anonymous user without thinking + * through any risk of credit-card testing using it. + * + * If the token is not totally transient it would be saved to civicrm_payment_token.token. + * + * @var string + */ + protected $paymentToken; + + /** + * Three digit currency code. + * + * @var string + */ + protected $currency; + + /** + * Payment processor generated string for the transaction ID. + * + * Note some gateways generate a reference for the order and one for the + * payment. This is for the payment reference and is saved to + * civicrm_financial_trxn.trxn_id. + * + * @var string + */ + protected $transactionID; + + /** + * Amount of money charged in fees by the payment processor. + * + * This is notified by (some) payment processers. + * + * @var float + */ + protected $feeAmount; + + /** + * Additional information returned by the payment processor regarding the payment outcome. + * + * This would normally be saved in civicrm_financial_trxn.trxn_result_code. + * + * @var string + */ + protected $trxnResultCode; + + /** + * Combined with recurFrequencyUnit this gives how often billing will take place. + * + * e.g every if this is 1 and recurFrequencyUnit is 'month' then it is every 1 month. + * + * @var int + */ + protected $recurFrequencyInterval; + + /** + * Combined with recurFrequencyInterval this gives how often billing will take place. + * + * e.g every if this is 'month' and recurFrequencyInterval is 1 then it is every 1 month. + * + * @var string + * month|day|year + */ + protected $recurFrequencyUnit; + /** * Passed in parameters. * @@ -166,6 +285,227 @@ abstract class CRM_Core_Payment { */ protected $inputParams = []; + /** + * @return int + */ + public function getContactID(): int { + return $this->contactID ?? $this->inputParams['contactID']; + } + + /** + * @param int $contactID + */ + public function setContactID(int $contactID) { + $this->contactID = $contactID; + } + + /** + * Getter for contributionRecurID. + * + * Ideally this would always be set by the calling function using the setting + * but we need to fall back to the historical passing on inputParams as a transition. + * + * In time we can add a notice if it's set in input params & not via a setter. + * + * @return int + */ + public function getContributionRecurID(): int { + return $this->contributionRecurID ?? $this->inputParams['contributionRecurID']; + } + + /** + * @param int $contributionRecurID + */ + public function setContributionRecurID(int $contributionRecurID) { + $this->contributionRecurID = $contributionRecurID; + } + + /** + * Getter for Payment Token. + * + * @return string + */ + public function getPaymentToken(): string { + return $this->paymentToken ?? $this->inputParams['token']; + } + + /** + * Setter for Payment Token. + * + * @param string $paymentToken + */ + public function setPaymentToken(string $paymentToken) { + $this->paymentToken = $paymentToken; + } + + /** + * Get gateway generated transaction ID. + * + * @return string + */ + public function getTransactionID(): string { + return $this->transactionID; + } + + /** + * Set gateway generated transaction ID for the payment. + * + * Note some gateways generate a reference for the order and one for the + * payment. This is for the payment reference and is saved to + * civicrm_financial_trxn.trxn_id. + * + * @param string $transactionID + */ + public function setTransactionID(string $transactionID) { + $this->transactionID = $transactionID; + } + + /** + * Get additional result information received from gateway. + * + * This is saved to civicrm_financial_trxn.trxn_result_code. + * + * @return string + */ + public function getTrxnResultCode(): string { + return $this->trxnResultCode; + } + + /** + * Set additional result information from gateway. + * + * This is saved to civicrm_financial_trxn.trxn_result_code. + * + * @param string $resultCode + */ + public function setTrxnResultCode(string $resultCode) { + $this->trxnResultCode = $resultCode; + } + + /** + * Get recurring frequency interval. + * + * @return int + */ + public function getRecurFrequencyInterval(): int { + return $this->recurFrequencyInterval ?? $this->inputParams['frequency_interval']; + } + + /** + * Set recurring frequency interval. + * + * @param int $recurFrequencyInterval + */ + public function setRecurFrequencyInterval(int $recurFrequencyInterval) { + $this->recurFrequencyInterval = $recurFrequencyInterval; + } + + /** + * Get recurring frequency unit. + * + * @return string + */ + public function getRecurFrequencyUnit(): string { + return $this->recurFrequencyUnit; + } + + /** + * Set recurring frequency unit. + * + * @param string $recurFrequencyUnit + */ + public function setRecurFrequencyUnit(string $recurFrequencyUnit) { + $this->recurFrequencyUnit = $recurFrequencyUnit ?? $this->inputParams['frequency_unit']; + } + + /** + * Get invoice ID (CiviCRM generated invoice reference). + * + * @return string + */ + public function getInvoiceID(): string { + return $this->invoiceID ?? $this->inputParams['invoiceID']; + } + + /** + * Set invoice ID (CiviCRM generated invoice reference). + * + * @param string $invoiceID + */ + public function setInvoiceID(string $invoiceID) { + $this->invoiceID = $invoiceID; + } + + /** + * Get whether the payment is recurring. + * + * @return bool + */ + public function isRecur(): bool { + return $this->isRecur; + } + + /** + * Set whether the payment is recurring. + * + * @param bool $isRecur + */ + public function setIsRecur(bool $isRecur) { + $this->isRecur = $isRecur ?? $this->inputParams['is_recur']; + } + + /** + * Get the description. + * + * This generates a description string from params if one has been passed in but + * ideally calling functions would use the setDescription function. + * + * @return string + */ + public function getDescription(): string { + if ($this->description) { + return $this->description; + } + if (isset($this->inputParams['description'])) { + $uninformativeStrings = [ + ts('Online Event Registration: '), + ts('Online Contribution: '), + ]; + $this->description = str_replace($uninformativeStrings, '', $this->inputParams['description']); + } + return $this->description; + } + + /** + * Set description. + * + * Generally this should be called when instantiating the processor to override + * getPaymentDescription, if desired. + * + * @param string $description + */ + public function setDescription(string $description) { + $this->description = $description; + } + + /** + * Get fee amount returned by processor. + * + * @return float + */ + public function getFeeAmount(): float { + return $this->feeAmount; + } + + /** + * Set fee amount returned by processor. + * + * @param float $feeAmount + */ + public function setFeeAmount(float $feeAmount) { + $this->feeAmount = $feeAmount; + } + /** * Get the contribution ID. * @@ -292,8 +632,6 @@ abstract class CRM_Core_Payment { * @todo move to factory class \Civi\Payment\System (or similar) * * @param array $params - * - * @return mixed */ public static function logPaymentNotification($params) { $message = 'payment_notification '; @@ -722,6 +1060,8 @@ abstract class CRM_Core_Payment { * Get the metadata of all the fields configured for this processor. * * @return array + * + * @throws \CiviCRM_API3_Exception */ protected function getAllFields() { $paymentFields = array_intersect_key($this->getPaymentFormFieldsMetadata(), array_flip($this->getPaymentFormFields())); @@ -764,6 +1104,8 @@ abstract class CRM_Core_Payment { * * @return array * field metadata + * + * @throws \Exception */ public function getPaymentFormFieldsMetadata() { //@todo convert credit card type into an option value @@ -1103,8 +1445,9 @@ abstract class CRM_Core_Payment { * * @return string */ - protected function getCurrency($params) { - return CRM_Utils_Array::value('currencyID', $params, CRM_Utils_Array::value('currency', $params)); + protected function getCurrency($params = []) { + $params = array_merge($params, (array) $this->inputParams); + return $this->currency ?? CRM_Utils_Array::value('currencyID', $params, CRM_Utils_Array::value('currency', $params)); } /** @@ -1112,12 +1455,14 @@ abstract class CRM_Core_Payment { * * Handle any inconsistency about how it is passed in here. * - * @param $params + * @param array $params * * @return string + * @throws \CRM_Core_Exception */ - protected function getAmount($params) { - return CRM_Utils_Money::format($params['amount'], NULL, NULL, TRUE); + protected function getAmount($params = []) { + $amount = $this->amount ?? $params['amount']; + return CRM_Utils_Money::format($amount, NULL, NULL, TRUE); } /** @@ -1665,7 +2010,7 @@ INNER JOIN civicrm_contribution con ON ( con.contribution_recur_id = rec.id ) * * @return string */ - protected function getPaymentDescription($params, $length = 24) { + protected function getPaymentDescription($params = [], $length = 24) { $parts = [ 'contactID', 'contributionID', @@ -1674,13 +2019,7 @@ INNER JOIN civicrm_contribution con ON ( con.contribution_recur_id = rec.id ) 'billing_last_name', ]; $validParts = []; - if (isset($params['description'])) { - $uninformativeStrings = [ - ts('Online Event Registration: '), - ts('Online Contribution: '), - ]; - $params['description'] = str_replace($uninformativeStrings, '', $params['description']); - } + $params['description'] = $this->getDescription(); foreach ($parts as $part) { if ((!empty($params[$part]))) { $validParts[] = $params[$part]; -- 2.25.1