2 namespace Civi\Payment
;
4 use InvalidArgumentException
;
6 use CRM_Core_PseudoConstant
;
11 * This class provides getters and setters for arguments needed by CRM_Core_Payment methods.
13 * The setters know how to validate each setting that they are responsible for.
15 * Different methods need different settings and the concept is that by passing
16 * in a property bag we can encapsulate the params needed for a particular
17 * method call, rather than setting arguments for different methods on the main
18 * CRM_Core_Payment object.
20 * This class is also supposed to help with transition away from array key naming nightmares.
23 class PropertyBag
implements \ArrayAccess
{
25 protected $props = ['default' => []];
27 protected static $propMap = [
29 'billingStreetAddress' => TRUE,
30 'billingSupplementalAddress1' => TRUE,
31 'billingSupplementalAddress2' => TRUE,
32 'billingSupplementalAddress3' => TRUE,
33 'billingCity' => TRUE,
34 'billingPostalCode' => TRUE,
35 'billingCounty' => TRUE,
36 'billingCountry' => TRUE,
38 'contact_id' => 'contactID',
39 'contributionID' => TRUE,
40 'contribution_id' => 'contributionID',
41 'contributionRecurID' => TRUE,
42 'contribution_recur_id' => 'contributionRecurID',
44 'currencyID' => 'currency',
45 'description' => TRUE,
48 'fee_amount' => 'feeAmount',
49 'first_name' => 'firstName',
52 'invoice_id' => 'invoiceID',
53 'isBackOffice' => TRUE,
54 'is_back_office' => 'isBackOffice',
56 'is_recur' => 'isRecur',
57 'last_name' => 'lastName',
59 'paymentToken' => TRUE,
60 'payment_token' => 'paymentToken',
62 'recurFrequencyInterval' => TRUE,
63 'frequency_interval' => 'recurFrequencyInterval',
64 'recurFrequencyUnit' => TRUE,
65 'frequency_unit' => 'recurFrequencyUnit',
66 'recurInstallments' => TRUE,
67 'installments' => 'recurInstallments',
68 'subscriptionId' => 'recurProcessorID',
69 'recurProcessorID' => TRUE,
70 'transactionID' => TRUE,
71 'transaction_id' => 'transactionID',
72 'trxnResultCode' => TRUE,
73 'isNotifyProcessorOnCancelRecur' => TRUE,
79 * Temporary, internal variable to help ease transition to PropertyBag.
80 * Used by cast() to suppress legacy warnings.
81 * For paymentprocessors that have not converted to propertyBag we need to support "legacy" properties - eg. "is_recur"
82 * without warnings. Setting this allows us to pass a propertyBag into doPayment() and expect it to "work" with
83 * existing payment processors.
85 protected $suppressLegacyWarnings = TRUE;
88 * Get the value of the suppressLegacyWarnings parameter
91 public function getSuppressLegacyWarnings() {
92 return $this->suppressLegacyWarnings
;
96 * Set the suppressLegacyWarnings parameter - useful for unit tests.
97 * Eg. you could set to FALSE for unit tests on a paymentprocessor to capture use of legacy keys in that processor
99 * @param bool $suppressLegacyWarnings
101 public function setSuppressLegacyWarnings(bool $suppressLegacyWarnings) {
102 $this->suppressLegacyWarnings
= $suppressLegacyWarnings;
106 * Get the property bag.
108 * This allows us to swap a 'might be an array might be a property bag'
109 * variable for a known PropertyBag.
111 * @param \Civi\Payment\PropertyBag|array $params
113 * @return \Civi\Payment\PropertyBag
115 public static function cast($params) {
116 if ($params instanceof self
) {
119 $propertyBag = new self();
120 $propertyBag->mergeLegacyInputParams($params);
125 * Just for unit testing.
132 * Implements ArrayAccess::offsetExists
134 * @param mixed $offset
135 * @return bool TRUE if we have that value (on our default store)
137 public function offsetExists ($offset): bool {
138 $prop = $this->handleLegacyPropNames($offset, TRUE);
139 // If there's no prop, assume it's a custom property.
140 $prop = $prop ??
$offset;
141 return array_key_exists($prop, $this->props
['default']);
145 * Implements ArrayAccess::offsetGet
147 * @param mixed $offset
150 public function offsetGet($offset) {
152 $prop = $this->handleLegacyPropNames($offset);
154 catch (InvalidArgumentException
$e) {
156 if (!$this->getSuppressLegacyWarnings()) {
157 CRM_Core_Error
::deprecatedFunctionWarning(
158 "proper getCustomProperty('$offset') for non-core properties. "
160 "PropertyBag array access to get '$offset'"
165 return $this->getCustomProperty($offset, 'default');
167 catch (BadMethodCallException
$e) {
168 CRM_Core_Error
::deprecatedFunctionWarning(
169 "proper setCustomProperty('$offset', \$value) to store the value (since it is not a core value), then access it with getCustomProperty('$offset'). NULL is returned but in future an exception will be thrown."
171 "PropertyBag array access to get unset property '$offset'"
177 if (!$this->getSuppressLegacyWarnings()) {
178 CRM_Core_Error
::deprecatedFunctionWarning(
179 "get" . ucfirst($offset) . "()",
180 "PropertyBag array access for core property '$offset'"
183 return $this->get($prop, 'default');
187 * Implements ArrayAccess::offsetSet
189 * @param mixed $offset
190 * @param mixed $value
192 public function offsetSet($offset, $value) {
194 $prop = $this->handleLegacyPropNames($offset);
196 catch (InvalidArgumentException
$e) {
197 // We need to make a lot of noise here, we're being asked to merge in
198 // something we can't validate because we don't know what this property is.
199 // This is fine if it's something particular to a payment processor
200 // (which should be using setCustomProperty) however it could also lead to
201 // things like 'my_weirly_named_contact_id'.
203 // From 5.28 we suppress this when using PropertyBag::cast() to ease transition.
204 if (!$this->suppressLegacyWarnings
) {
205 CRM_Core_Error
::deprecatedFunctionWarning(
206 "proper setCustomProperty('$offset', \$value) for non-core properties. "
208 "PropertyBag array access to set '$offset'"
211 $this->setCustomProperty($offset, $value, 'default');
215 // Coerce legacy values that were in use but shouldn't be in our new way of doing things.
216 if ($prop === 'feeAmount' && $value === '') {
217 // At least the following classes pass in ZLS for feeAmount.
218 // CRM_Core_Payment_AuthorizeNetTest::testCreateSingleNowDated
219 // CRM_Core_Payment_AuthorizeNetTest::testCreateSinglePostDated
223 // These lines are here (and not in try block) because the catch must only
224 // catch the case when the prop is custom.
225 $setter = 'set' . ucfirst($prop);
226 if (!$this->suppressLegacyWarnings
) {
227 CRM_Core_Error
::deprecatedFunctionWarning(
229 "PropertyBag array access to set core property '$offset'"
232 $this->$setter($value, 'default');
236 * Implements ArrayAccess::offsetUnset
238 * @param mixed $offset
240 public function offsetUnset ($offset) {
241 $prop = $this->handleLegacyPropNames($offset);
242 unset($this->props
['default'][$prop]);
246 * @param string $prop
247 * @param bool $silent if TRUE return NULL instead of throwing an exception. This is because offsetExists should be safe and not throw exceptions.
248 * @return string canonical name.
249 * @throws \InvalidArgumentException if prop name not known.
251 protected function handleLegacyPropNames($prop, $silent = FALSE) {
252 $newName = static::$propMap[$prop] ??
NULL;
253 if ($newName === TRUE) {
254 // Good, modern name.
257 // Handling for legacy addition of billing details.
258 if ($newName === NULL && substr($prop, -2) === '-' . \CRM_Core_BAO_LocationType
::getBilling()
259 && isset(static::$propMap[substr($prop, 0, -2)])
261 $newName = substr($prop, 0, -2);
264 if ($newName === NULL) {
266 // Only for use by offsetExists
269 throw new \
InvalidArgumentException("Unknown property '$prop'.");
271 // Remaining case is legacy name that's been translated.
272 if (!$this->getSuppressLegacyWarnings()) {
273 CRM_Core_Error
::deprecatedFunctionWarning("Canonical property name '$newName'", "Legacy property name '$prop'");
282 * @param mixed $prop Valid property name
283 * @param string $label e.g. 'default'
287 protected function get($prop, $label) {
288 if (array_key_exists($prop, $this->props
[$label] ??
[])) {
289 return $this->props
[$label][$prop];
291 throw new \
BadMethodCallException("Property '$prop' has not been set.");
297 * @param mixed $prop Valid property name
298 * @param string $label e.g. 'default'
299 * @param mixed $value
301 * @return PropertyBag $this object so you can chain set setters.
303 protected function set($prop, $label, $value) {
304 $this->props
[$label][$prop] = $value;
311 protected function coercePseudoConstantStringToInt(string $baoName, string $field, $input) {
312 if (is_numeric($input)) {
313 // We've been given a numeric ID.
316 elseif (is_string($input)) {
317 // We've been given a named instrument.
318 $_ = (int) CRM_Core_PseudoConstant
::getKey($baoName, $field, $input);
321 throw new InvalidArgumentException("Expected an integer ID or a String name for $field.");
324 throw new InvalidArgumentException("Expected an integer greater than 0 for $field.");
331 public function has($prop, $label = 'default') {
332 // We do NOT translate legacy prop names since only new code should be
333 // using this method, and new code should be using canonical names.
334 // $prop = $this->handleLegacyPropNames($prop);
335 return isset($this->props
[$label][$prop]);
339 * This is used to merge values from an array.
340 * It's a transitional, internal function and should not be used!
344 public function mergeLegacyInputParams($data) {
345 // Suppress legacy warnings for merging an array of data as this
346 // suits our migration plan at this moment. Future behaviour may differ.
347 // @see https://github.com/civicrm/civicrm-core/pull/17643
348 $suppressLegacyWarnings = $this->getSuppressLegacyWarnings();
349 $this->setSuppressLegacyWarnings(TRUE);
350 foreach ($data as $key => $value) {
351 if ($value !== NULL && $value !== '') {
352 $this->offsetSet($key, $value);
355 $this->setSuppressLegacyWarnings($suppressLegacyWarnings);
359 * Throw an exception if any of the props is unset.
361 * @param array $props Array of proper property names (no legacy aliases allowed).
363 * @return PropertyBag
365 public function require(array $props) {
367 foreach ($props as $prop) {
368 if (!isset($this->props
['default'][$prop])) {
373 throw new \
InvalidArgumentException("Required properties missing: " . implode(', ', $missing));
378 // Public getters, setters.
381 * Get a property by its name (but still using its getter).
383 * @param string $prop valid property name, like contactID
384 * @param bool $allowUnset If TRUE, return the default value if the property is
385 * not set - normal behaviour would be to throw an exception.
386 * @param mixed $default
387 * @param string $label e.g. 'default' or 'old' or 'new'
391 public function getter($prop, $allowUnset = FALSE, $default = NULL, $label = 'default') {
393 if ((static::$propMap[$prop] ??
NULL) === TRUE) {
394 // This is a standard property that will have a getter method.
395 $getter = 'get' . ucfirst($prop);
396 return (!$allowUnset ||
$this->has($prop, $label))
397 ?
$this->$getter($label)
401 // This is not a property name we know, but they could be requesting a
403 return (!$allowUnset ||
$this->has($prop, $label))
404 ?
$this->getCustomProperty($prop, $label)
409 * Set a property by its name (but still using its setter).
411 * @param string $prop valid property name, like contactID
412 * @param mixed $value
413 * @param string $label e.g. 'default' or 'old' or 'new'
417 public function setter($prop, $value = NULL, $label = 'default') {
418 if ((static::$propMap[$prop] ??
NULL) === TRUE) {
419 // This is a standard property.
420 $setter = 'set' . ucfirst($prop);
421 return $this->$setter($value, $label);
423 // We don't allow using the setter for custom properties.
424 throw new \
BadMethodCallException("Cannot use generic setter with non-standard properties; you must use setCustomProperty for custom properties.");
428 * Get the monetary amount.
430 public function getAmount($label = 'default') {
431 return $this->get('amount', $label);
435 * Set the monetary amount.
437 * - We expect to be called with a string amount with optional decimals using
438 * a '.' as the decimal point (not a ',').
440 * - We're ok with floats/ints being passed in, too, but we'll cast them to a
443 * - Negatives are fine.
445 * @see https://github.com/civicrm/civicrm-core/pull/18219
447 * @param string|float|int $value
448 * @param string $label
450 public function setAmount($value, $label = 'default') {
451 if (!is_numeric($value)) {
452 throw new \
InvalidArgumentException("setAmount requires a numeric amount value");
454 return $this->set('amount', $label, filter_var($value, FILTER_SANITIZE_NUMBER_FLOAT
, FILTER_FLAG_ALLOW_FRACTION
));
458 * BillingStreetAddress getter.
462 public function getBillingStreetAddress($label = 'default') {
463 return $this->get('billingStreetAddress', $label);
467 * BillingStreetAddress setter.
469 * @param string $input
470 * @param string $label e.g. 'default'
472 public function setBillingStreetAddress($input, $label = 'default') {
473 return $this->set('billingStreetAddress', $label, (string) $input);
477 * BillingSupplementalAddress1 getter.
481 public function getBillingSupplementalAddress1($label = 'default') {
482 return $this->get('billingSupplementalAddress1', $label);
486 * BillingSupplementalAddress1 setter.
488 * @param string $input
489 * @param string $label e.g. 'default'
491 public function setBillingSupplementalAddress1($input, $label = 'default') {
492 return $this->set('billingSupplementalAddress1', $label, (string) $input);
496 * BillingSupplementalAddress2 getter.
500 public function getBillingSupplementalAddress2($label = 'default') {
501 return $this->get('billingSupplementalAddress2', $label);
505 * BillingSupplementalAddress2 setter.
507 * @param string $input
508 * @param string $label e.g. 'default'
510 public function setBillingSupplementalAddress2($input, $label = 'default') {
511 return $this->set('billingSupplementalAddress2', $label, (string) $input);
515 * BillingSupplementalAddress3 getter.
519 public function getBillingSupplementalAddress3($label = 'default') {
520 return $this->get('billingSupplementalAddress3', $label);
524 * BillingSupplementalAddress3 setter.
526 * @param string $input
527 * @param string $label e.g. 'default'
529 public function setBillingSupplementalAddress3($input, $label = 'default') {
530 return $this->set('billingSupplementalAddress3', $label, (string) $input);
534 * BillingCity getter.
538 public function getBillingCity($label = 'default') {
539 return $this->get('billingCity', $label);
543 * BillingCity setter.
545 * @param string $input
546 * @param string $label e.g. 'default'
548 * @return \Civi\Payment\PropertyBag
550 public function setBillingCity($input, $label = 'default') {
551 return $this->set('billingCity', $label, (string) $input);
555 * BillingPostalCode getter.
559 public function getBillingPostalCode($label = 'default') {
560 return $this->get('billingPostalCode', $label);
564 * BillingPostalCode setter.
566 * @param string $input
567 * @param string $label e.g. 'default'
569 public function setBillingPostalCode($input, $label = 'default') {
570 return $this->set('billingPostalCode', $label, (string) $input);
574 * BillingCounty getter.
578 public function getBillingCounty($label = 'default') {
579 return $this->get('billingCounty', $label);
583 * BillingCounty setter.
585 * Nb. we can't validate this unless we have the country ID too, so we don't.
587 * @param string $input
588 * @param string $label e.g. 'default'
590 public function setBillingCounty($input, $label = 'default') {
591 return $this->set('billingCounty', $label, (string) $input);
595 * BillingCountry getter.
599 public function getBillingCountry($label = 'default') {
600 return $this->get('billingCountry', $label);
604 * BillingCountry setter.
606 * Nb. We require and we store a 2 character country code.
608 * @param string $input
609 * @param string $label e.g. 'default'
611 public function setBillingCountry($input, $label = 'default') {
612 if (!is_string($input) ||
strlen($input) !== 2) {
613 throw new \
InvalidArgumentException("setBillingCountry expects ISO 3166-1 alpha-2 country code.");
615 if (!CRM_Core_PseudoConstant
::getKey('CRM_Core_BAO_Address', 'country_id', $input)) {
616 throw new \
InvalidArgumentException("setBillingCountry expects ISO 3166-1 alpha-2 country code.");
618 return $this->set('billingCountry', $label, (string) $input);
624 public function getContactID($label = 'default'): int {
625 return $this->get('contactID', $label);
629 * @param int $contactID
630 * @param string $label
632 public function setContactID($contactID, $label = 'default') {
633 // We don't use this because it counts zero as positive: CRM_Utils_Type::validate($contactID, 'Positive');
634 if (!($contactID > 0)) {
635 throw new InvalidArgumentException("ContactID must be a positive integer");
638 return $this->set('contactID', $label, (int) $contactID);
642 * Getter for contributionID.
645 * @param string $label
647 public function getContributionID($label = 'default') {
648 return $this->get('contributionID', $label);
652 * @param int $contributionID
653 * @param string $label e.g. 'default'
655 public function setContributionID($contributionID, $label = 'default') {
656 // We don't use this because it counts zero as positive: CRM_Utils_Type::validate($contactID, 'Positive');
657 if (!($contributionID > 0)) {
658 throw new InvalidArgumentException("ContributionID must be a positive integer");
661 return $this->set('contributionID', $label, (int) $contributionID);
665 * Getter for contributionRecurID.
668 * @param string $label
670 public function getContributionRecurID($label = 'default') {
671 return $this->get('contributionRecurID', $label);
675 * @param int $contributionRecurID
676 * @param string $label e.g. 'default'
678 * @return \Civi\Payment\PropertyBag
680 public function setContributionRecurID($contributionRecurID, $label = 'default') {
681 // We don't use this because it counts zero as positive: CRM_Utils_Type::validate($contactID, 'Positive');
682 if (!($contributionRecurID > 0)) {
683 throw new InvalidArgumentException('ContributionRecurID must be a positive integer');
686 return $this->set('contributionRecurID', $label, (int) $contributionRecurID);
690 * Three character currency code.
692 * https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3
694 * @param string $label e.g. 'default'
696 public function getCurrency($label = 'default') {
697 return $this->get('currency', $label);
701 * Three character currency code.
703 * @param string $value
704 * @param string $label e.g. 'default'
706 public function setCurrency($value, $label = 'default') {
707 if (!preg_match('/^[A-Z]{3}$/', $value)) {
708 throw new \
InvalidArgumentException("Attemted to setCurrency with a value that was not an ISO 3166-1 alpha 3 currency code");
710 return $this->set('currency', $label, $value);
715 * @param string $label
719 public function getDescription($label = 'default') {
720 return $this->get('description', $label);
724 * @param string $description
725 * @param string $label e.g. 'default'
727 public function setDescription($description, $label = 'default') {
728 // @todo this logic was copied from a commit that then got deleted. Is it good?
729 $uninformativeStrings = [
730 ts('Online Event Registration: '),
731 ts('Online Contribution: '),
733 $cleanedDescription = str_replace($uninformativeStrings, '', $description);
734 return $this->set('description', $label, $cleanedDescription);
742 public function getEmail($label = 'default') {
743 return $this->get('email', $label);
749 * @param string $email
750 * @param string $label e.g. 'default'
752 public function setEmail($email, $label = 'default') {
753 return $this->set('email', $label, (string) $email);
757 * Amount of money charged in fees by the payment processor.
759 * This is notified by (some) payment processers.
761 * @param string $label
765 public function getFeeAmount($label = 'default') {
766 return $this->get('feeAmount', $label);
770 * @param string $feeAmount
771 * @param string $label e.g. 'default'
773 public function setFeeAmount($feeAmount, $label = 'default') {
774 if (!is_numeric($feeAmount)) {
775 throw new \
InvalidArgumentException("feeAmount must be a number.");
777 return $this->set('feeAmount', $label, (float) $feeAmount);
785 public function getFirstName($label = 'default') {
786 return $this->get('firstName', $label);
792 * @param string $firstName
793 * @param string $label e.g. 'default'
795 public function setFirstName($firstName, $label = 'default') {
796 return $this->set('firstName', $label, (string) $firstName);
800 * Getter for invoiceID.
802 * @param string $label
804 * @return string|null
806 public function getInvoiceID($label = 'default') {
807 return $this->get('invoiceID', $label);
811 * @param string $invoiceID
812 * @param string $label e.g. 'default'
814 public function setInvoiceID($invoiceID, $label = 'default') {
815 return $this->set('invoiceID', $label, $invoiceID);
819 * Getter for isBackOffice.
821 * @param string $label
825 public function getIsBackOffice($label = 'default'):bool {
826 // @todo should this return FALSE instead of exception to keep current situation?
827 return $this->get('isBackOffice', $label);
831 * @param bool $isBackOffice
832 * @param string $label e.g. 'default'
834 public function setIsBackOffice($isBackOffice, $label = 'default') {
835 if (is_null($isBackOffice)) {
836 throw new \
InvalidArgumentException("isBackOffice must be a bool, received NULL.");
838 return $this->set('isBackOffice', $label, (bool) $isBackOffice);
842 * Getter for isRecur.
844 * @param string $label
848 public function getIsRecur($label = 'default'):bool {
849 if (!$this->has('isRecur')) {
852 return $this->get('isRecur', $label);
856 * @param bool $isRecur
857 * @param string $label e.g. 'default'
859 public function setIsRecur($isRecur, $label = 'default') {
860 if (is_null($isRecur)) {
861 throw new \
InvalidArgumentException("isRecur must be a bool, received NULL.");
863 return $this->set('isRecur', $label, (bool) $isRecur);
867 * Set whether the user has selected to notify the processor of a cancellation request.
869 * When cancelling the user may be presented with an option to notify the processor. The payment
870 * processor can take their response, if present, into account.
873 * @param string $label e.g. 'default'
875 * @return \Civi\Payment\PropertyBag
877 public function setIsNotifyProcessorOnCancelRecur($value, $label = 'default') {
878 return $this->set('isNotifyProcessorOnCancelRecur', $label, (bool) $value);
882 * Get whether the user has selected to notify the processor of a cancellation request.
884 * When cancelling the user may be presented with an option to notify the processor. The payment
885 * processor can take their response, if present, into account.
887 * @param string $label e.g. 'default'
889 * @return \Civi\Payment\PropertyBag
891 public function getIsNotifyProcessorOnCancelRecur($label = 'default') {
892 return $this->get('isNotifyProcessorOnCancelRecur', $label);
900 public function getLastName($label = 'default') {
901 return $this->get('lastName', $label);
907 * @param string $lastName
908 * @param string $label e.g. 'default'
910 public function setLastName($lastName, $label = 'default') {
911 return $this->set('lastName', $label, (string) $lastName);
915 * Getter for payment processor generated string for charging.
917 * A payment token could be a single use token (e.g generated by
918 * a client side script) or a token that permits recurring or on demand charging.
920 * The key thing is it is passed to the processor in lieu of card details to
921 * initiate a payment.
923 * Generally if a processor is going to pass in a payment token generated through
924 * javascript it would add 'payment_token' to the array it returns in it's
925 * implementation of getPaymentFormFields. This will add a hidden 'payment_token' field to
926 * the form. A good example is client side encryption where credit card details are replaced by
927 * an encrypted token using a gateway provided javascript script. In this case the javascript will
928 * remove the credit card details from the form before submitting and populate the payment_token field.
930 * A more complex example is used by paypal checkout where the payment token is generated
931 * via a pre-approval process. In that case the doPreApproval function is called on the processor
932 * class to get information to then interact with paypal via js, finally getting a payment token.
933 * (at this stage the pre-approve api is not in core but that is likely to change - we just need
934 * to think about the permissions since we don't want to expose to anonymous user without thinking
935 * through any risk of credit-card testing using it.
937 * If the token is not totally transient it would be saved to civicrm_payment_token.token.
939 * @param string $label
941 * @return string|null
943 public function getPaymentToken($label = 'default') {
944 return $this->get('paymentToken', $label);
948 * @param string $paymentToken
949 * @param string $label e.g. 'default'
951 public function setPaymentToken($paymentToken, $label = 'default') {
952 return $this->set('paymentToken', $label, $paymentToken);
960 public function getPhone($label = 'default') {
961 return $this->get('phone', $label);
967 * @param string $phone
968 * @param string $label e.g. 'default'
970 public function setPhone($phone, $label = 'default') {
971 return $this->set('phone', $label, (string) $phone);
975 * Combined with recurFrequencyUnit this gives how often billing will take place.
977 * e.g every if this is 1 and recurFrequencyUnit is 'month' then it is every 1 month.
980 public function getRecurFrequencyInterval($label = 'default') {
981 return $this->get('recurFrequencyInterval', $label);
985 * @param int $recurFrequencyInterval
986 * @param string $label e.g. 'default'
988 public function setRecurFrequencyInterval($recurFrequencyInterval, $label = 'default') {
989 if (!($recurFrequencyInterval > 0)) {
990 throw new InvalidArgumentException("recurFrequencyInterval must be a positive integer");
993 return $this->set('recurFrequencyInterval', $label, (int) $recurFrequencyInterval);
997 * Getter for recurFrequencyUnit.
998 * Combined with recurFrequencyInterval this gives how often billing will take place.
1000 * e.g every if this is 'month' and recurFrequencyInterval is 1 then it is every 1 month.
1003 * @param string $label
1005 * @return string month|day|year
1007 public function getRecurFrequencyUnit($label = 'default') {
1008 return $this->get('recurFrequencyUnit', $label);
1012 * @param string $recurFrequencyUnit month|day|week|year
1013 * @param string $label e.g. 'default'
1015 public function setRecurFrequencyUnit($recurFrequencyUnit, $label = 'default') {
1016 if (!preg_match('/^day|week|month|year$/', $recurFrequencyUnit)) {
1017 throw new \
InvalidArgumentException("recurFrequencyUnit must be day|week|month|year");
1019 return $this->set('recurFrequencyUnit', $label, $recurFrequencyUnit);
1023 * @param string $label
1027 public function getRecurInstallments($label = 'default') {
1028 return $this->get('recurInstallments', $label);
1032 * @param int $recurInstallments
1033 * @param string $label
1035 * @return \Civi\Payment\PropertyBag
1036 * @throws \CRM_Core_Exception
1038 public function setRecurInstallments($recurInstallments, $label = 'default') {
1039 // Counts zero as positive which is ok - means no installments
1040 if (!\CRM_Utils_Type
::validate($recurInstallments, 'Positive')) {
1041 throw new InvalidArgumentException('recurInstallments must be 0 or a positive integer');
1044 return $this->set('recurInstallments', $label, (int) $recurInstallments);
1048 * Set the unique payment processor service provided ID for a particular subscription.
1050 * Nb. this is stored in civicrm_contribution_recur.processor_id and is NOT
1051 * in any way related to the payment processor ID.
1053 * @param string $label
1055 * @return string|null
1057 public function getRecurProcessorID($label = 'default') {
1058 return $this->get('recurProcessorID', $label);
1062 * Set the unique payment processor service provided ID for a particular
1065 * See https://github.com/civicrm/civicrm-core/pull/17292 for discussion
1066 * of how this function accepting NULL fits with standard / planned behaviour.
1068 * @param string|null $input
1069 * @param string $label e.g. 'default'
1071 * @return \Civi\Payment\PropertyBag
1073 public function setRecurProcessorID($input, $label = 'default') {
1074 if ($input === '') {
1077 if (strlen($input) > 255 ||
in_array($input, [FALSE, 0], TRUE)) {
1078 throw new \
InvalidArgumentException('processorID field has max length of 255');
1080 return $this->set('recurProcessorID', $label, $input);
1084 * Getter for payment processor generated string for the transaction ID.
1086 * Note some gateways generate a reference for the order and one for the
1087 * payment. This is for the payment reference and is saved to
1088 * civicrm_financial_trxn.trxn_id.
1090 * @param string $label
1092 * @return string|null
1094 public function getTransactionID($label = 'default') {
1095 return $this->get('transactionID', $label);
1099 * @param string $transactionID
1100 * @param string $label e.g. 'default'
1102 public function setTransactionID($transactionID, $label = 'default') {
1103 return $this->set('transactionID', $label, $transactionID);
1107 * Getter for trxnResultCode.
1109 * Additional information returned by the payment processor regarding the
1112 * This would normally be saved in civicrm_financial_trxn.trxn_result_code.
1115 * @param string $label
1117 * @return string|null
1119 public function getTrxnResultCode($label = 'default') {
1120 return $this->get('trxnResultCode', $label);
1124 * @param string $trxnResultCode
1125 * @param string $label e.g. 'default'
1127 public function setTrxnResultCode($trxnResultCode, $label = 'default') {
1128 return $this->set('trxnResultCode', $label, $trxnResultCode);
1131 // Custom Properties.
1134 * Sometimes we may need to pass in things that are specific to the Payment
1137 * @param string $prop
1138 * @param string $label e.g. 'default' or 'old' or 'new'
1141 * @throws InvalidArgumentException if trying to use this against a non-custom property.
1143 public function getCustomProperty($prop, $label = 'default') {
1144 if (isset(static::$propMap[$prop])) {
1145 throw new \
InvalidArgumentException("Attempted to get '$prop' via getCustomProperty - must use using its getter.");
1148 if (!array_key_exists($prop, $this->props
[$label] ??
[])) {
1149 throw new \
BadMethodCallException("Property '$prop' has not been set.");
1151 return $this->props
[$label][$prop] ??
NULL;
1155 * We have to leave validation to the processor, but we can still give them a
1156 * way to store their data on this PropertyBag
1158 * @param string $prop
1159 * @param mixed $value
1160 * @param string $label e.g. 'default' or 'old' or 'new'
1162 * @throws InvalidArgumentException if trying to use this against a non-custom property.
1164 public function setCustomProperty($prop, $value, $label = 'default') {
1165 if (isset(static::$propMap[$prop])) {
1166 throw new \
InvalidArgumentException("Attempted to set '$prop' via setCustomProperty - must use using its setter.");
1168 $this->props
[$label][$prop] = $value;