CRM/Core/Payment/Form.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | Copyright CiviCRM LLC. All rights reserved.                        |
   5  |                                                                    |
   6  | This work is published under the GNU AGPLv3 license with some      |
   7  | permitted exceptions and without any warranty. For full license    |
   8  | and copyright information, see https://civicrm.org/licensing       |
   9  +--------------------------------------------------------------------+
  10  */
  11
  12 /**
  13  * Class for constructing the payment processor block.
  14  *
  15  * @package CRM
  16  * @copyright CiviCRM LLC https://civicrm.org/licensing
  17  */
  18 class CRM_Core_Payment_Form {
  19
  20   /**
  21    * Add payment fields depending on payment processor.
  22    *
  23    * The payment processor can implement the following functions to override the built in fields.
  24    *
  25    *  - getPaymentFormFields()
  26    *  - getPaymentFormFieldsMetadata()
  27    *  (planned - getBillingDetailsFormFields(), getBillingDetailsFormFieldsMetadata()
  28    *
  29    *  Note that this code is written to accommodate the possibility CiviCRM will switch to implementing pay later as a manual processor in future
  30    *
  31    * @param CRM_Contribute_Form_AbstractEditPayment|CRM_Contribute_Form_Contribution_Main $form
  32    * @param array $processor
  33    *   Array of properties including 'object' as loaded from CRM_Financial_BAO_PaymentProcessor::getPaymentProcessors.
  34    * @param int $billing_profile_id
  35    *   Display billing fields even for pay later.
  36    * @param bool $isBackOffice
  37    *   Is this a back office function? If so the option to suppress the cvn needs to be evaluated.
  38    * @param int $paymentInstrumentID
  39    *   ID of the payment processor.
  40    */
  41   public static function setPaymentFieldsByProcessor(&$form, $processor, $billing_profile_id = NULL, $isBackOffice = FALSE, $paymentInstrumentID = NULL) {
  42     $form->billingFieldSets = [];
  43     // Load the pay-later processor
  44     // @todo load this right up where the other processors are loaded initially.
  45     if (empty($processor)) {
  46       $processor = CRM_Financial_BAO_PaymentProcessor::getPayment(0);
  47     }
  48
  49     $processor['object']->setBillingProfile($billing_profile_id);
  50     $processor['object']->setBackOffice($isBackOffice);
  51     if (isset($paymentInstrumentID)) {
  52       $processor['object']->setPaymentInstrumentID($paymentInstrumentID);
  53     }
  54     $paymentTypeName = self::getPaymentTypeName($processor);
  55     $form->assign('paymentTypeName', $paymentTypeName);
  56     $form->assign('paymentTypeLabel', self::getPaymentLabel($processor['object']));
  57     $form->assign('isBackOffice', $isBackOffice);
  58     $form->_paymentFields = $form->billingFieldSets[$paymentTypeName]['fields'] = self::getPaymentFieldMetadata($processor);
  59     $form->_paymentFields = array_merge($form->_paymentFields, self::getBillingAddressMetadata($processor, $form->_bltID));
  60     $form->assign('paymentFields', self::getPaymentFields($processor));
  61     self::setBillingAddressFields($form, $processor);
  62     // @todo - this may be obsolete - although potentially it could be used to re-order things in the form.
  63     $form->billingFieldSets['billing_name_address-group']['fields'] = [];
  64   }
  65
  66   /**
  67    * Add general billing fields.
  68    *
  69    * @param CRM_Core_Form $form
  70    * @param CRM_Core_Payment $processor
  71    */
  72   protected static function setBillingAddressFields(&$form, $processor) {
  73     $billingID = $form->_bltID;
  74     $smarty = CRM_Core_Smarty::singleton();
  75     $smarty->assign('billingDetailsFields', self::getBillingAddressFields($processor, $billingID));
  76   }
  77
  78   /**
  79    * Add the payment fields to the template.
  80    *
  81    * Generally this is the payment processor fields & the billing fields required
  82    * for the payment processor. However, this has been complicated by adding
  83    * pay later billing fields into this mix
  84    *
  85    * We now have the situation where the required fields cannot be set as required
  86    * on the form level if they are required for the payment processor, as another
  87    * processor might be selected and the validation will then be incorrect.
  88    *
  89    * However, if they are required for pay later we DO set them on the form level,
  90    * presumably assuming they will be required whatever happens.
  91    *
  92    * As a side-note this seems to re-enforce the argument for making pay later
  93    * operate as a payment processor rather than as a 'special thing on its own'.
  94    *
  95    * @param CRM_Core_Form $form
  96    *   Form that the payment fields are to be added to.
  97    * @param array $paymentFields
  98    *   Fields that are to be shown on the payment form.
  99    */
 100   protected static function addCommonFields(&$form, $paymentFields) {
 101     $requiredPaymentFields = $paymentFieldsMetadata = [];
 102     foreach ($paymentFields as $name => $field) {
 103       $field['extra'] = $field['extra'] ?? NULL;
 104       if ($field['htmlType'] == 'chainSelect') {
 105         $form->addChainSelect($field['name'], ['required' => FALSE]);
 106       }
 107       else {
 108         $form->add($field['htmlType'],
 109           $field['name'],
 110           $field['title'],
 111           $field['attributes'],
 112           $field['is_required'],
 113           $field['extra']
 114         );
 115       }
 116       // This will cause the fields to be marked as required - but it is up to the payment processor to
 117       // validate it.
 118       $requiredPaymentFields[$field['name']] = $field['is_required'];
 119       $paymentFieldsMetadata[$field['name']] = $field;
 120     }
 121
 122     $form->assign('paymentFieldsMetadata', $paymentFieldsMetadata);
 123     $form->assign('requiredPaymentFields', $requiredPaymentFields);
 124   }
 125
 126   /**
 127    * Get the payment fields that apply to this processor.
 128    *
 129    * @param array $paymentProcessor
 130    *
 131    * @todo sometimes things like the country alter the required fields (e.g direct debit fields). We should possibly
 132    * set these before calling getPaymentFormFields (as we identify them).
 133    *
 134    * @return array
 135    */
 136   public static function getPaymentFields($paymentProcessor) {
 137     return $paymentProcessor['object']->getPaymentFormFields();
 138   }
 139
 140   /**
 141    * @param array $paymentProcessor
 142    *
 143    * @return array
 144    */
 145   public static function getPaymentFieldMetadata($paymentProcessor) {
 146     return array_intersect_key($paymentProcessor['object']->getPaymentFormFieldsMetadata(), array_flip(self::getPaymentFields($paymentProcessor)));
 147   }
 148
 149   /**
 150    * Get the billing fields that apply to this processor.
 151    *
 152    * @param array $paymentProcessor
 153    * @param int $billingLocationID
 154    *   ID of billing location type.
 155    *
 156    * @todo sometimes things like the country alter the required fields (e.g postal code). We should possibly
 157    * set these before calling getPaymentFormFields (as we identify them).
 158    *
 159    * @return array
 160    */
 161   public static function getBillingAddressFields($paymentProcessor, $billingLocationID) {
 162     return $paymentProcessor['object']->getBillingAddressFields($billingLocationID);
 163   }
 164
 165   /**
 166    * @param array $paymentProcessor
 167    *
 168    * @param int $billingLocationID
 169    *
 170    * @return array
 171    * @throws \CRM_Core_Exception
 172    */
 173   public static function getBillingAddressMetadata($paymentProcessor, $billingLocationID) {
 174     $paymentProcessorObject = Civi\Payment\System::singleton()->getByProcessor($paymentProcessor);
 175     return array_intersect_key(
 176       $paymentProcessorObject->getBillingAddressFieldsMetadata($billingLocationID),
 177       array_flip(self::getBillingAddressFields($paymentProcessor, $billingLocationID))
 178     );
 179   }
 180
 181   /**
 182    * @param array $paymentProcessor
 183    *
 184    * @return string
 185    */
 186   public static function getPaymentTypeName($paymentProcessor) {
 187     return $paymentProcessor['object']->getPaymentTypeName();
 188   }
 189
 190   /**
 191    * @param array $paymentProcessor
 192    *
 193    * @return string
 194    */
 195   public static function getPaymentTypeLabel($paymentProcessor) {
 196     return $paymentProcessor->getPaymentTypeLabel();
 197   }
 198
 199   /**
 200    * @param CRM_Contribute_Form_AbstractEditPayment|CRM_Contribute_Form_Contribution_Main|CRM_Core_Payment_ProcessorForm|CRM_Contribute_Form_UpdateBilling $form
 201    * @param array $processor
 202    *   Array of properties including 'object' as loaded from CRM_Financial_BAO_PaymentProcessor::getPaymentProcessors.
 203    * @param int|string $billing_profile_id
 204    *   Id of a profile to be passed to the processor for the processor to merge with it's required fields.
 205    *   (currently only implemented by manual/ pay-later processor)
 206    *
 207    * @param bool $isBackOffice
 208    *   Is this a backoffice form. This could affect the display of the cvn or whether some processors show,
 209    *   although the distinction is losing it's meaning as front end forms are used for back office and a permission
 210    *   for the 'enter without cvn' is probably more appropriate. Paypal std does not support another user
 211    *   entering details but once again the issue is not back office but 'another user'.
 212    * @param int $paymentInstrumentID
 213    *   Payment instrument ID.
 214    *
 215    * @return bool
 216    */
 217   public static function buildPaymentForm(&$form, $processor, $billing_profile_id, $isBackOffice, $paymentInstrumentID = NULL) {
 218     //if the form has address fields assign to the template so the js can decide what billing fields to show
 219     $profileAddressFields = $form->get('profileAddressFields');
 220     if (!empty($profileAddressFields)) {
 221       $form->assign('profileAddressFields', $profileAddressFields);
 222     }
 223
 224     if (!empty($processor['object']) && $processor['object']->buildForm($form)) {
 225       return NULL;
 226     }
 227
 228     self::setPaymentFieldsByProcessor($form, $processor, $billing_profile_id, $isBackOffice, $paymentInstrumentID);
 229     self::addCommonFields($form, $form->_paymentFields);
 230     self::addRules($form, $form->_paymentFields);
 231     return (!empty($form->_paymentFields));
 232   }
 233
 234   /**
 235    * @param CRM_Core_Form $form
 236    * @param array $paymentFields
 237    *   Array of properties including 'object' as loaded from CRM_Financial_BAO_PaymentProcessor::getPaymentProcessors.
 238    * @param $paymentFields
 239    */
 240   protected static function addRules(&$form, $paymentFields) {
 241     foreach ($paymentFields as $paymentField => $fieldSpecs) {
 242       if (!empty($fieldSpecs['rules'])) {
 243         foreach ($fieldSpecs['rules'] as $rule) {
 244           $form->addRule($paymentField,
 245             $rule['rule_message'],
 246             $rule['rule_name'],
 247             $rule['rule_parameters']
 248           );
 249         }
 250       }
 251     }
 252   }
 253
 254   /**
 255    * Validate the payment instrument values before passing it to the payment processor.
 256    *
 257    * We want this to be able to be overridden by the payment processor, and default to using
 258    * this object's validCreditCard for credit cards (implemented as the default in the Payment class).
 259    *
 260    * @param int $payment_processor_id
 261    * @param array $values
 262    * @param array $errors
 263    * @param int $billing_profile_id
 264    */
 265   public static function validatePaymentInstrument($payment_processor_id, $values, &$errors, $billing_profile_id) {
 266     $payment = Civi\Payment\System::singleton()->getById($payment_processor_id);
 267     $payment->setBillingProfile($billing_profile_id);
 268     $payment->validatePaymentInstrument($values, $errors);
 269   }
 270
 271   /**
 272    * Set default values for the form.
 273    *
 274    * @param CRM_Core_Form $form
 275    * @param int $contactID
 276    */
 277   public static function setDefaultValues(&$form, $contactID) {
 278     $billingDefaults = $form->getProfileDefaults('Billing', $contactID);
 279     $form->_defaults = array_merge($form->_defaults, $billingDefaults);
 280
 281     // set default country & state from config if no country set
 282     // note the effect of this is to set the billing country to default to the site default
 283     // country if the person has an address but no country (for anonymous country is set above)
 284     // this could have implications if the billing profile is filled but hidden.
 285     // this behaviour has been in place for a while but the use of js to hide things has increased
 286     if (empty($form->_defaults["billing_country_id-{$form->_bltID}"])) {
 287       $form->_defaults["billing_country_id-{$form->_bltID}"] = CRM_Core_Config::singleton()->defaultContactCountry;
 288     }
 289     if (empty($form->_defaults["billing_state_province_id-{$form->_bltID}"])) {
 290       $form->_defaults["billing_state_province_id-{$form->_bltID}"] = CRM_Core_Config::singleton()
 291         ->defaultContactStateProvince;
 292     }
 293   }
 294
 295   /**
 296    * Make sure that credit card number and cvv are valid.
 297    * Called within the scope of a QF formRule function
 298    *
 299    * @param array $values
 300    * @param array $errors
 301    * @param int $processorID
 302    */
 303   public static function validateCreditCard($values, &$errors, $processorID = NULL) {
 304     if (!empty($values['credit_card_type']) || !empty($values['credit_card_number'])) {
 305       if (!empty($values['credit_card_type'])) {
 306         $processorCards = CRM_Financial_BAO_PaymentProcessor::getCreditCards($processorID);
 307         if (!empty($processorCards) && !in_array($values['credit_card_type'], $processorCards)) {
 308           $errors['credit_card_type'] = ts('This processor does not support credit card type %1', [1 => $values['credit_card_type']]);
 309         }
 310       }
 311       if (!empty($values['credit_card_number']) &&
 312         !CRM_Utils_Rule::creditCardNumber($values['credit_card_number'], $values['credit_card_type'])
 313       ) {
 314         $errors['credit_card_number'] = ts('Please enter a valid Card Number');
 315       }
 316       if (!empty($values['cvv2']) &&
 317         !CRM_Utils_Rule::cvv($values['cvv2'], $values['credit_card_type'])
 318       ) {
 319         $errors['cvv2'] = ts('Please enter a valid Card Verification Number');
 320       }
 321     }
 322   }
 323
 324   /**
 325    * Map address fields.
 326    *
 327    * @param int $id
 328    * @param array $src
 329    * @param array $dst
 330    * @param bool $reverse
 331    */
 332   public static function mapParams($id, $src, &$dst, $reverse = FALSE) {
 333     $map = [
 334       'first_name' => 'billing_first_name',
 335       'middle_name' => 'billing_middle_name',
 336       'last_name' => 'billing_last_name',
 337       'email' => "email-$id",
 338       'street_address' => "billing_street_address-$id",
 339       'supplemental_address_1' => "billing_supplemental_address_1-$id",
 340       'city' => "billing_city-$id",
 341       'state_province' => "billing_state_province-$id",
 342       'postal_code' => "billing_postal_code-$id",
 343       'country' => "billing_country-$id",
 344       'contactID' => 'contact_id',
 345     ];
 346
 347     foreach ($map as $n => $v) {
 348       if (!$reverse) {
 349         if (isset($src[$n])) {
 350           $dst[$v] = $src[$n];
 351         }
 352       }
 353       else {
 354         if (isset($src[$v])) {
 355           $dst[$n] = $src[$v];
 356         }
 357       }
 358     }
 359
 360     //CRM-19469 provide option for returning modified params
 361     return $dst;
 362   }
 363
 364   /**
 365    * Get the credit card expiration month.
 366    * The date format for this field should typically be "M Y" (ex: Feb 2011) or "m Y" (02 2011)
 367    * See CRM-9017
 368    *
 369    * @param $src
 370    *
 371    * @return int
 372    */
 373   public static function getCreditCardExpirationMonth($src) {
 374     if ($month = CRM_Utils_Array::value('M', $src['credit_card_exp_date'])) {
 375       return $month;
 376     }
 377
 378     return $src['credit_card_exp_date']['m'] ?? NULL;
 379   }
 380
 381   /**
 382    * Get the credit card expiration year.
 383    * The date format for this field should typically be "M Y" (ex: Feb 2011) or "m Y" (02 2011)
 384    * This function exists only to make it consistent with getCreditCardExpirationMonth
 385    *
 386    * @param $src
 387    *
 388    * @return int
 389    */
 390   public static function getCreditCardExpirationYear($src) {
 391     return $src['credit_card_exp_date']['Y'] ?? NULL;
 392   }
 393
 394   /**
 395    * Get the label for the processor.
 396    *
 397    * We do not use a label if there are no enterable fields.
 398    *
 399    * @param \CRM_Core_Payment $processor
 400    *
 401    * @return string
 402    */
 403   public static function getPaymentLabel($processor) {
 404     $isVisible = FALSE;
 405     $paymentTypeLabel = self::getPaymentTypeLabel($processor);
 406     foreach (self::getPaymentFieldMetadata(['object' => $processor]) as $paymentField) {
 407       if ($paymentField['htmlType'] !== 'hidden') {
 408         $isVisible = TRUE;
 409       }
 410     }
 411     return $isVisible ? $paymentTypeLabel : '';
 412
 413   }
 414
 415 }