CRM/Core/Payment/Form.php

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