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
{
24 protected $props = ['default' => []];
26 protected static $propMap = [
27 'billingStreetAddress' => TRUE,
28 'billingSupplementalAddress1' => TRUE,
29 'billingSupplementalAddress2' => TRUE,
30 'billingSupplementalAddress3' => TRUE,
31 'billingCity' => TRUE,
32 'billingPostalCode' => TRUE,
33 'billingCounty' => TRUE,
34 'billingCountry' => TRUE,
36 'contact_id' => 'contactID',
37 'contributionID' => TRUE,
38 'contribution_id' => 'contributionID',
39 'contributionRecurID' => TRUE,
40 'contribution_recur_id' => 'contributionRecurID',
42 'currencyID' => 'currency',
43 'description' => TRUE,
46 'fee_amount' => 'feeAmount',
47 'first_name' => 'firstName',
50 'invoice_id' => 'invoiceID',
51 'isBackOffice' => TRUE,
52 'is_back_office' => 'isBackOffice',
54 'is_recur' => 'isRecur',
55 'last_name' => 'lastName',
57 'paymentToken' => TRUE,
58 'payment_token' => 'paymentToken',
60 'recurFrequencyInterval' => TRUE,
61 'frequency_interval' => 'recurFrequencyInterval',
62 'recurFrequencyUnit' => TRUE,
63 'frequency_unit' => 'recurFrequencyUnit',
64 'recurProcessorID' => TRUE,
65 'transactionID' => TRUE,
66 'transaction_id' => 'transactionID',
67 'trxnResultCode' => TRUE,
71 * Get the property bag.
73 * This allows us to swap a 'might be an array might be a property bag'
74 * variable for a known PropertyBag.
76 * @param \Civi\Payment\PropertyBag|array $params
78 * @return \Civi\Payment\PropertyBag
80 public static function cast($params) {
81 if ($params instanceof self
) {
84 $propertyBag = new self();
85 $propertyBag->mergeLegacyInputParams($params);
90 * @var string Just for unit testing.
95 * Implements ArrayAccess::offsetExists
97 * @param mixed $offset
98 * @return bool TRUE if we have that value (on our default store)
100 public function offsetExists ($offset): bool {
101 $prop = $this->handleLegacyPropNames($offset);
102 return isset($this->props
['default'][$prop]);
106 * Implements ArrayAccess::offsetGet
108 * @param mixed $offset
111 public function offsetGet ($offset) {
112 $prop = $this->handleLegacyPropNames($offset);
113 return $this->get($prop, 'default');
117 * Implements ArrayAccess::offsetSet
119 * @param mixed $offset
120 * @param mixed $value
122 public function offsetSet($offset, $value) {
124 $prop = $this->handleLegacyPropNames($offset);
126 catch (InvalidArgumentException
$e) {
127 // We need to make a lot of noise here, we're being asked to merge in
128 // something we can't validate because we don't know what this property is.
129 // This is fine if it's something particular to a payment processor
130 // (which should be using setCustomProperty) however it could also lead to
131 // things like 'my_weirly_named_contact_id'.
132 $this->legacyWarning($e->getMessage() . " We have merged this in for now as a custom property. Please rewrite your code to use PropertyBag->setCustomProperty if it is a genuinely custom property, or a standardised setter like PropertyBag->setContactID for standard properties");
133 $this->setCustomProperty($offset, $value, 'default');
137 // Coerce legacy values that were in use but shouldn't be in our new way of doing things.
138 if ($prop === 'feeAmount' && $value === '') {
139 // At least the following classes pass in ZLS for feeAmount.
140 // CRM_Core_Payment_AuthorizeNetTest::testCreateSingleNowDated
141 // CRM_Core_Payment_AuthorizeNetTest::testCreateSinglePostDated
145 // These lines are here (and not in try block) because the catch must only
146 // catch the case when the prop is custom.
147 $setter = 'set' . ucfirst($prop);
148 $this->$setter($value, 'default');
152 * Implements ArrayAccess::offsetUnset
154 * @param mixed $offset
156 public function offsetUnset ($offset) {
157 $prop = $this->handleLegacyPropNames($offset);
158 unset($this->props
['default'][$prop]);
162 * @param string $message
164 protected function legacyWarning($message) {
165 $message = "Deprecated code: $message";
166 $this->lastWarning
= $message;
167 Civi
::log()->warning($message);
171 * @param string $prop
172 * @return string canonical name.
173 * @throws \InvalidArgumentException if prop name not known.
175 protected function handleLegacyPropNames($prop) {
176 $newName = static::$propMap[$prop] ??
NULL;
177 if ($newName === TRUE) {
178 // Good, modern name.
181 if ($newName === NULL) {
182 throw new \
InvalidArgumentException("Unknown property '$prop'.");
184 // Remaining case is legacy name that's been translated.
185 $this->legacyWarning("We have translated '$prop' to '$newName' for you, but please update your code to use the propper setters and getters.");
192 * @param mixed $prop Valid property name
193 * @param string $label e.g. 'default'
195 protected function get($prop, $label) {
196 if (isset($this->props
['default'][$prop])) {
197 return $this->props
[$label][$prop];
199 throw new \
BadMethodCallException("Property '$prop' has not been set.");
205 * @param mixed $prop Valid property name
206 * @param string $label e.g. 'default'
207 * @param mixed $value
209 * @return PropertyBag $this object so you can chain set setters.
211 protected function set($prop, $label = 'default', $value) {
212 $this->props
[$label][$prop] = $value;
219 protected function coercePseudoConstantStringToInt(string $baoName, string $field, $input) {
220 if (is_numeric($input)) {
221 // We've been given a numeric ID.
224 elseif (is_string($input)) {
225 // We've been given a named instrument.
226 $_ = (int) CRM_Core_PseudoConstant
::getKey($baoName, $field, $input);
229 throw new InvalidArgumentException("Expected an integer ID or a String name for $field.");
232 throw new InvalidArgumentException("Expected an integer greater than 0 for $field.");
239 public function has($prop, $label = 'default') {
240 // We do NOT translate legacy prop names since only new code should be
241 // using this method, and new code should be using canonical names.
242 // $prop = $this->handleLegacyPropNames($prop);
243 return isset($this->props
[$label][$prop]);
247 * This is used to merge values from an array.
248 * It's a transitional function and should not be used!
252 public function mergeLegacyInputParams($data) {
253 $this->legacyWarning("We have merged input params into the property bag for now but please rewrite code to not use this.");
254 foreach ($data as $key => $value) {
255 if ($value !== NULL) {
256 $this->offsetSet($key, $value);
262 * Throw an exception if any of the props is unset.
264 * @param array $props Array of proper property names (no legacy aliases allowed).
266 * @return PropertyBag
268 public function require(array $props) {
270 foreach ($props as $prop) {
271 if (!isset($this->props
['default'][$prop])) {
276 throw new \
InvalidArgumentException("Required properties missing: " . implode(', ', $missing));
281 // Public getters, setters.
284 * Get a property by its name (but still using its getter).
286 * @param string $prop valid property name, like contactID
287 * @param bool $allowUnset If TRUE, return the default value if the property is
288 * not set - normal behaviour would be to throw an exception.
289 * @param mixed $default
290 * @param string $label e.g. 'default' or 'old' or 'new'
294 public function getter($prop, $allowUnset = FALSE, $default = NULL, $label = 'default') {
296 if ((static::$propMap[$prop] ??
NULL) === TRUE) {
297 // This is a standard property that will have a getter method.
298 $getter = 'get' . ucfirst($prop);
299 return (!$allowUnset ||
$this->has($prop, $label))
300 ?
$this->$getter($label)
304 // This is not a property name we know, but they could be requesting a
306 return (!$allowUnset ||
$this->has($prop, $label))
307 ?
$this->getCustomProperty($prop, $label)
312 * Set a property by its name (but still using its setter).
314 * @param string $prop valid property name, like contactID
315 * @param mixed $value
316 * @param string $label e.g. 'default' or 'old' or 'new'
320 public function setter($prop, $value = NULL, $label = 'default') {
321 if ((static::$propMap[$prop] ??
NULL) === TRUE) {
322 // This is a standard property.
323 $setter = 'set' . ucfirst($prop);
324 return $this->$setter($value, $label);
326 // We don't allow using the setter for custom properties.
327 throw new \
BadMethodCallException("Cannot use generic setter with non-standard properties; you must use setCustomProperty for custom properties.");
331 * Get the monetary amount.
333 public function getAmount($label = 'default') {
334 return $this->get('amount', $label);
338 * Get the monetary amount.
340 public function setAmount($value, $label = 'default') {
341 if (!is_numeric($value)) {
342 throw new \
InvalidArgumentException("setAmount requires a numeric amount value");
345 return $this->set('amount', CRM_Utils_Money
::format($value, NULL, NULL, TRUE), $label);
349 * BillingStreetAddress getter.
353 public function getBillingStreetAddress($label = 'default') {
354 return $this->get('billingStreetAddress', $label);
358 * BillingStreetAddress setter.
360 * @param string $input
361 * @param string $label e.g. 'default'
363 public function setBillingStreetAddress($input, $label = 'default') {
364 return $this->set('billingStreetAddress', $label, (string) $input);
368 * BillingSupplementalAddress1 getter.
372 public function getBillingSupplementalAddress1($label = 'default') {
373 return $this->get('billingSupplementalAddress1', $label);
377 * BillingSupplementalAddress1 setter.
379 * @param string $input
380 * @param string $label e.g. 'default'
382 public function setBillingSupplementalAddress1($input, $label = 'default') {
383 return $this->set('billingSupplementalAddress1', $label, (string) $input);
387 * BillingSupplementalAddress2 getter.
391 public function getBillingSupplementalAddress2($label = 'default') {
392 return $this->get('billingSupplementalAddress2', $label);
396 * BillingSupplementalAddress2 setter.
398 * @param string $input
399 * @param string $label e.g. 'default'
401 public function setBillingSupplementalAddress2($input, $label = 'default') {
402 return $this->set('billingSupplementalAddress2', $label, (string) $input);
406 * BillingSupplementalAddress3 getter.
410 public function getBillingSupplementalAddress3($label = 'default') {
411 return $this->get('billingSupplementalAddress3', $label);
415 * BillingSupplementalAddress3 setter.
417 * @param string $input
418 * @param string $label e.g. 'default'
420 public function setBillingSupplementalAddress3($input, $label = 'default') {
421 return $this->set('billingSupplementalAddress3', $label, (string) $input);
425 * BillingCity getter.
429 public function getBillingCity($label = 'default') {
430 return $this->get('billingCity', $label);
434 * BillingCity setter.
436 * @param string $input
437 * @param string $label e.g. 'default'
439 public function setBillingCity($input, $label = 'default') {
440 return $this->set('billingCity', $label, (string) $input);
444 * BillingPostalCode getter.
448 public function getBillingPostalCode($label = 'default') {
449 return $this->get('billingPostalCode', $label);
453 * BillingPostalCode setter.
455 * @param string $input
456 * @param string $label e.g. 'default'
458 public function setBillingPostalCode($input, $label = 'default') {
459 return $this->set('billingPostalCode', $label, (string) $input);
463 * BillingCounty getter.
467 public function getBillingCounty($label = 'default') {
468 return $this->get('billingCounty', $label);
472 * BillingCounty setter.
474 * Nb. we can't validate this unless we have the country ID too, so we don't.
476 * @param string $input
477 * @param string $label e.g. 'default'
479 public function setBillingCounty($input, $label = 'default') {
480 return $this->set('billingCounty', $label, (string) $input);
484 * BillingCountry getter.
488 public function getBillingCountry($label = 'default') {
489 return $this->get('billingCountry', $label);
493 * BillingCountry setter.
495 * Nb. We require and we store a 2 character country code.
497 * @param string $input
498 * @param string $label e.g. 'default'
500 public function setBillingCountry($input, $label = 'default') {
501 if (!is_string($input) ||
strlen($input) !== 2) {
502 throw new \
InvalidArgumentException("setBillingCountry expects ISO 3166-1 alpha-2 country code.");
504 if (!CRM_Core_PseudoConstant
::getKey('CRM_Core_BAO_Address', 'country_id', $input)) {
505 throw new \
InvalidArgumentException("setBillingCountry expects ISO 3166-1 alpha-2 country code.");
507 return $this->set('billingCountry', $label, (string) $input);
513 public function getContactID($label = 'default'): int {
514 return $this->get('contactID', $label);
518 * @param int $contactID
519 * @param string $label
521 public function setContactID($contactID, $label = 'default') {
522 // We don't use this because it counts zero as positive: CRM_Utils_Type::validate($contactID, 'Positive');
523 if (!($contactID > 0)) {
524 throw new InvalidArgumentException("ContactID must be a positive integer");
527 return $this->set('contactID', $label, (int) $contactID);
531 * Getter for contributionID.
534 * @param string $label
536 public function getContributionID($label = 'default') {
537 return $this->get('contributionID', $label);
541 * @param int $contributionID
542 * @param string $label e.g. 'default'
544 public function setContributionID($contributionID, $label = 'default') {
545 // We don't use this because it counts zero as positive: CRM_Utils_Type::validate($contactID, 'Positive');
546 if (!($contributionID > 0)) {
547 throw new InvalidArgumentException("ContributionID must be a positive integer");
550 return $this->set('contributionID', $label, (int) $contributionID);
554 * Getter for contributionRecurID.
557 * @param string $label
559 public function getContributionRecurID($label = 'default') {
560 return $this->get('contributionRecurID', $label);
564 * @param int $contributionRecurID
565 * @param string $label e.g. 'default'
567 public function setContributionRecurID($contributionRecurID, $label = 'default') {
568 // We don't use this because it counts zero as positive: CRM_Utils_Type::validate($contactID, 'Positive');
569 if (!($contributionRecurID > 0)) {
570 throw new InvalidArgumentException("ContributionRecurID must be a positive integer");
573 return $this->set('contributionRecurID', $label, (int) $contributionRecurID);
577 * Three character currency code.
579 * https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3
581 * @param string $label e.g. 'default'
583 public function getCurrency($label = 'default') {
584 return $this->get('currency', $label);
588 * Three character currency code.
590 * @param string $value
591 * @param string $label e.g. 'default'
593 public function setCurrency($value, $label = 'default') {
594 if (!preg_match('/^[A-Z]{3}$/', $value)) {
595 throw new \
InvalidArgumentException("Attemted to setCurrency with a value that was not an ISO 3166-1 alpha 3 currency code");
597 return $this->set('currency', $label, $value);
602 * @param string $label
606 public function getDescription($label = 'default') {
607 return $this->get('description', $label);
611 * @param string $description
612 * @param string $label e.g. 'default'
614 public function setDescription($description, $label = 'default') {
615 // @todo this logic was copied from a commit that then got deleted. Is it good?
616 $uninformativeStrings = [
617 ts('Online Event Registration: '),
618 ts('Online Contribution: '),
620 $cleanedDescription = str_replace($uninformativeStrings, '', $description);
621 return $this->set('description', $label, $cleanedDescription);
629 public function getEmail($label = 'default') {
630 return $this->get('email', $label);
636 * @param string $email
637 * @param string $label e.g. 'default'
639 public function setEmail($email, $label = 'default') {
640 return $this->set('email', $label, (string) $email);
644 * Amount of money charged in fees by the payment processor.
646 * This is notified by (some) payment processers.
648 * @param string $label
652 public function getFeeAmount($label = 'default') {
653 return $this->get('feeAmount', $label);
657 * @param string $feeAmount
658 * @param string $label e.g. 'default'
660 public function setFeeAmount($feeAmount, $label = 'default') {
661 if (!is_numeric($feeAmount)) {
662 throw new \
InvalidArgumentException("feeAmount must be a number.");
664 return $this->set('feeAmount', $label, (float) $feeAmount);
672 public function getFirstName($label = 'default') {
673 return $this->get('firstName', $label);
679 * @param string $firstName
680 * @param string $label e.g. 'default'
682 public function setFirstName($firstName, $label = 'default') {
683 return $this->set('firstName', $label, (string) $firstName);
687 * Getter for invoiceID.
689 * @param string $label
691 * @return string|null
693 public function getInvoiceID($label = 'default') {
694 return $this->get('invoiceID', $label);
698 * @param string $invoiceID
699 * @param string $label e.g. 'default'
701 public function setInvoiceID($invoiceID, $label = 'default') {
702 return $this->set('invoiceID', $label, $invoiceID);
706 * Getter for isBackOffice.
708 * @param string $label
712 public function getIsBackOffice($label = 'default'):bool {
713 // @todo should this return FALSE instead of exception to keep current situation?
714 return $this->get('isBackOffice', $label);
718 * @param bool $isBackOffice
719 * @param string $label e.g. 'default'
721 public function setIsBackOffice($isBackOffice, $label = 'default') {
722 if (is_null($isBackOffice)) {
723 throw new \
InvalidArgumentException("isBackOffice must be a bool, received NULL.");
725 return $this->set('isBackOffice', $label, (bool) $isBackOffice);
729 * Getter for isRecur.
731 * @param string $label
735 public function getIsRecur($label = 'default'):bool {
736 return $this->get('isRecur', $label);
740 * @param bool $isRecur
741 * @param string $label e.g. 'default'
743 public function setIsRecur($isRecur, $label = 'default') {
744 if (is_null($isRecur)) {
745 throw new \
InvalidArgumentException("isRecur must be a bool, received NULL.");
747 return $this->set('isRecur', $label, (bool) $isRecur);
755 public function getLastName($label = 'default') {
756 return $this->get('lastName', $label);
762 * @param string $lastName
763 * @param string $label e.g. 'default'
765 public function setLastName($lastName, $label = 'default') {
766 return $this->set('lastName', $label, (string) $lastName);
770 * Getter for payment processor generated string for charging.
772 * A payment token could be a single use token (e.g generated by
773 * a client side script) or a token that permits recurring or on demand charging.
775 * The key thing is it is passed to the processor in lieu of card details to
776 * initiate a payment.
778 * Generally if a processor is going to pass in a payment token generated through
779 * javascript it would add 'payment_token' to the array it returns in it's
780 * implementation of getPaymentFormFields. This will add a hidden 'payment_token' field to
781 * the form. A good example is client side encryption where credit card details are replaced by
782 * an encrypted token using a gateway provided javascript script. In this case the javascript will
783 * remove the credit card details from the form before submitting and populate the payment_token field.
785 * A more complex example is used by paypal checkout where the payment token is generated
786 * via a pre-approval process. In that case the doPreApproval function is called on the processor
787 * class to get information to then interact with paypal via js, finally getting a payment token.
788 * (at this stage the pre-approve api is not in core but that is likely to change - we just need
789 * to think about the permissions since we don't want to expose to anonymous user without thinking
790 * through any risk of credit-card testing using it.
792 * If the token is not totally transient it would be saved to civicrm_payment_token.token.
794 * @param string $label
796 * @return string|null
798 public function getPaymentToken($label = 'default') {
799 return $this->get('paymentToken', $label);
803 * @param string $paymentToken
804 * @param string $label e.g. 'default'
806 public function setPaymentToken($paymentToken, $label = 'default') {
807 return $this->set('paymentToken', $label, $paymentToken);
815 public function getPhone($label = 'default') {
816 return $this->get('phone', $label);
822 * @param string $phone
823 * @param string $label e.g. 'default'
825 public function setPhone($phone, $label = 'default') {
826 return $this->set('phone', $label, (string) $phone);
830 * Combined with recurFrequencyUnit this gives how often billing will take place.
832 * e.g every if this is 1 and recurFrequencyUnit is 'month' then it is every 1 month.
835 public function getRecurFrequencyInterval($label = 'default') {
836 return $this->get('recurFrequencyInterval', $label);
840 * @param int $recurFrequencyInterval
841 * @param string $label e.g. 'default'
843 public function setRecurFrequencyInterval($recurFrequencyInterval, $label = 'default') {
844 if (!($recurFrequencyInterval > 0)) {
845 throw new InvalidArgumentException("recurFrequencyInterval must be a positive integer");
848 return $this->set('recurFrequencyInterval', $label, (int) $recurFrequencyInterval);
852 * Getter for recurFrequencyUnit.
853 * Combined with recurFrequencyInterval this gives how often billing will take place.
855 * e.g every if this is 'month' and recurFrequencyInterval is 1 then it is every 1 month.
858 * @param string $label
860 * @return string month|day|year
862 public function getRecurFrequencyUnit($label = 'default') {
863 return $this->get('recurFrequencyUnit', $label);
867 * @param string $recurFrequencyUnit month|day|week|year
868 * @param string $label e.g. 'default'
870 public function setRecurFrequencyUnit($recurFrequencyUnit, $label = 'default') {
871 if (!preg_match('/^day|week|month|year$/', $recurFrequencyUnit)) {
872 throw new \
InvalidArgumentException("recurFrequencyUnit must be day|week|month|year");
874 return $this->set('recurFrequencyUnit', $label, $recurFrequencyUnit);
878 * Set the unique payment processor service provided ID for a particular subscription.
880 * Nb. this is stored in civicrm_contribution_recur.processor_id and is NOT
881 * in any way related to the payment processor ID.
885 public function getRecurProcessorID($label = 'default') {
886 return $this->get('recurProcessorID', $label);
890 * Set the unique payment processor service provided ID for a particular
893 * @param string $input
894 * @param string $label e.g. 'default'
896 public function setRecurProcessorID($input, $label = 'default') {
897 if (empty($input) ||
strlen($input) > 255) {
898 throw new \
InvalidArgumentException("processorID field has max length of 255");
900 return $this->set('recurProcessorID', $label, $input);
904 * Getter for payment processor generated string for the transaction ID.
906 * Note some gateways generate a reference for the order and one for the
907 * payment. This is for the payment reference and is saved to
908 * civicrm_financial_trxn.trxn_id.
910 * @param string $label
912 * @return string|null
914 public function getTransactionID($label = 'default') {
915 return $this->get('transactionID', $label);
919 * @param string $transactionID
920 * @param string $label e.g. 'default'
922 public function setTransactionID($transactionID, $label = 'default') {
923 return $this->set('transactionID', $label, $transactionID);
927 * Getter for trxnResultCode.
929 * Additional information returned by the payment processor regarding the
932 * This would normally be saved in civicrm_financial_trxn.trxn_result_code.
935 * @param string $label
937 * @return string|null
939 public function getTrxnResultCode($label = 'default') {
940 return $this->get('trxnResultCode', $label);
944 * @param string $trxnResultCode
945 * @param string $label e.g. 'default'
947 public function setTrxnResultCode($trxnResultCode, $label = 'default') {
948 return $this->set('trxnResultCode', $label, $trxnResultCode);
951 // Custom Properties.
954 * Sometimes we may need to pass in things that are specific to the Payment
957 * @param string $prop
958 * @param string $label e.g. 'default' or 'old' or 'new'
961 * @throws InvalidArgumentException if trying to use this against a non-custom property.
963 public function getCustomProperty($prop, $label = 'default') {
964 if (isset(static::$propMap[$prop])) {
965 throw new \
InvalidArgumentException("Attempted to get '$prop' via getCustomProperty - must use using its getter.");
967 return $this->props
[$label][$prop] ??
NULL;
971 * We have to leave validation to the processor, but we can still give them a
972 * way to store their data on this PropertyBag
974 * @param string $prop
975 * @param mixed $value
976 * @param string $label e.g. 'default' or 'old' or 'new'
978 * @throws InvalidArgumentException if trying to use this against a non-custom property.
980 public function setCustomProperty($prop, $value, $label = 'default') {
981 if (isset(static::$propMap[$prop])) {
982 throw new \
InvalidArgumentException("Attempted to set '$prop' via setCustomProperty - must use using its setter.");
984 $this->props
[$label][$prop] = $value;