3 +--------------------------------------------------------------------+
4 | Copyright CiviCRM LLC. All rights reserved. |
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 +--------------------------------------------------------------------+
13 * Class for constructing the payment processor block.
16 * @copyright CiviCRM LLC https://civicrm.org/licensing
18 class CRM_Core_Payment_Form
{
21 * Add payment fields depending on payment processor.
23 * The payment processor can implement the following functions to override the built in fields.
25 * - getPaymentFormFields()
26 * - getPaymentFormFieldsMetadata()
27 * (planned - getBillingDetailsFormFields(), getBillingDetailsFormFieldsMetadata()
29 * Note that this code is written to accommodate the possibility CiviCRM will switch to implementing pay later as a manual processor in future
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.
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);
49 $processor['object']->setBillingProfile($billing_profile_id);
50 $processor['object']->setBackOffice($isBackOffice);
51 $processor['object']->setPaymentInstrumentID($paymentInstrumentID);
52 $paymentTypeName = self
::getPaymentTypeName($processor);
53 $form->assign('paymentTypeName', $paymentTypeName);
54 $form->assign('paymentTypeLabel', self
::getPaymentLabel($processor['object']));
55 $form->assign('isBackOffice', $isBackOffice);
56 $form->_paymentFields
= $form->billingFieldSets
[$paymentTypeName]['fields'] = self
::getPaymentFieldMetadata($processor);
57 $form->_paymentFields
= array_merge($form->_paymentFields
, self
::getBillingAddressMetadata($processor, $form->_bltID
));
58 $form->assign('paymentFields', self
::getPaymentFields($processor));
59 self
::setBillingAddressFields($form, $processor);
60 // @todo - this may be obsolete - although potentially it could be used to re-order things in the form.
61 $form->billingFieldSets
['billing_name_address-group']['fields'] = [];
65 * Add general billing fields.
67 * @param CRM_Core_Form $form
68 * @param CRM_Core_Payment $processor
70 protected static function setBillingAddressFields(&$form, $processor) {
71 $billingID = $form->_bltID
;
72 $smarty = CRM_Core_Smarty
::singleton();
73 $smarty->assign('billingDetailsFields', self
::getBillingAddressFields($processor, $billingID));
77 * Add the payment fields to the template.
79 * Generally this is the payment processor fields & the billing fields required
80 * for the payment processor. However, this has been complicated by adding
81 * pay later billing fields into this mix
83 * We now have the situation where the required fields cannot be set as required
84 * on the form level if they are required for the payment processor, as another
85 * processor might be selected and the validation will then be incorrect.
87 * However, if they are required for pay later we DO set them on the form level,
88 * presumably assuming they will be required whatever happens.
90 * As a side-note this seems to re-enforce the argument for making pay later
91 * operate as a payment processor rather than as a 'special thing on its own'.
93 * @param CRM_Core_Form $form
94 * Form that the payment fields are to be added to.
95 * @param array $paymentFields
96 * Fields that are to be shown on the payment form.
98 protected static function addCommonFields(&$form, $paymentFields) {
99 $requiredPaymentFields = $paymentFieldsMetadata = [];
100 foreach ($paymentFields as $name => $field) {
101 $field['extra'] = isset($field['extra']) ?
$field['extra'] : NULL;
102 if ($field['htmlType'] == 'chainSelect') {
103 $form->addChainSelect($field['name'], ['required' => FALSE]);
106 $form->add($field['htmlType'],
109 $field['attributes'],
114 // This will cause the fields to be marked as required - but it is up to the payment processor to
116 $requiredPaymentFields[$field['name']] = $field['is_required'];
117 $paymentFieldsMetadata[$field['name']] = $field;
120 $form->assign('paymentFieldsMetadata', $paymentFieldsMetadata);
121 $form->assign('requiredPaymentFields', $requiredPaymentFields);
125 * Get the payment fields that apply to this processor.
127 * @param array $paymentProcessor
129 * @todo sometimes things like the country alter the required fields (e.g direct debit fields). We should possibly
130 * set these before calling getPaymentFormFields (as we identify them).
134 public static function getPaymentFields($paymentProcessor) {
135 return $paymentProcessor['object']->getPaymentFormFields();
139 * @param array $paymentProcessor
143 public static function getPaymentFieldMetadata($paymentProcessor) {
144 return array_intersect_key($paymentProcessor['object']->getPaymentFormFieldsMetadata(), array_flip(self
::getPaymentFields($paymentProcessor)));
148 * Get the billing fields that apply to this processor.
150 * @param array $paymentProcessor
151 * @param int $billingLocationID
152 * ID of billing location type.
154 * @todo sometimes things like the country alter the required fields (e.g postal code). We should possibly
155 * set these before calling getPaymentFormFields (as we identify them).
159 public static function getBillingAddressFields($paymentProcessor, $billingLocationID) {
160 return $paymentProcessor['object']->getBillingAddressFields($billingLocationID);
164 * @param array $paymentProcessor
166 * @param int $billingLocationID
169 * @throws \CRM_Core_Exception
171 public static function getBillingAddressMetadata($paymentProcessor, $billingLocationID) {
172 $paymentProcessorObject = Civi\Payment\System
::singleton()->getByProcessor($paymentProcessor);
173 return array_intersect_key(
174 $paymentProcessorObject->getBillingAddressFieldsMetadata($billingLocationID),
175 array_flip(self
::getBillingAddressFields($paymentProcessor, $billingLocationID))
180 * @param array $paymentProcessor
184 public static function getPaymentTypeName($paymentProcessor) {
185 return $paymentProcessor['object']->getPaymentTypeName();
189 * @param array $paymentProcessor
193 public static function getPaymentTypeLabel($paymentProcessor) {
194 return $paymentProcessor->getPaymentTypeLabel();
198 * @param CRM_Contribute_Form_AbstractEditPayment|CRM_Contribute_Form_Contribution_Main|CRM_Core_Payment_ProcessorForm|CRM_Contribute_Form_UpdateBilling $form
199 * @param array $processor
200 * Array of properties including 'object' as loaded from CRM_Financial_BAO_PaymentProcessor::getPaymentProcessors.
201 * @param int|string $billing_profile_id
202 * Id of a profile to be passed to the processor for the processor to merge with it's required fields.
203 * (currently only implemented by manual/ pay-later processor)
205 * @param bool $isBackOffice
206 * Is this a backoffice form. This could affect the display of the cvn or whether some processors show,
207 * although the distinction is losing it's meaning as front end forms are used for back office and a permission
208 * for the 'enter without cvn' is probably more appropriate. Paypal std does not support another user
209 * entering details but once again the issue is not back office but 'another user'.
210 * @param int $paymentInstrumentID
211 * Payment instrument ID.
215 public static function buildPaymentForm(&$form, $processor, $billing_profile_id, $isBackOffice, $paymentInstrumentID = NULL) {
216 //if the form has address fields assign to the template so the js can decide what billing fields to show
217 $profileAddressFields = $form->get('profileAddressFields');
218 if (!empty($profileAddressFields)) {
219 $form->assign('profileAddressFields', $profileAddressFields);
222 if (!empty($processor['object']) && $processor['object']->buildForm($form)) {
226 self
::setPaymentFieldsByProcessor($form, $processor, $billing_profile_id, $isBackOffice, $paymentInstrumentID);
227 self
::addCommonFields($form, $form->_paymentFields
);
228 self
::addRules($form, $form->_paymentFields
);
229 return (!empty($form->_paymentFields
));
233 * @param CRM_Core_Form $form
234 * @param array $paymentFields
235 * Array of properties including 'object' as loaded from CRM_Financial_BAO_PaymentProcessor::getPaymentProcessors.
236 * @param $paymentFields
238 protected static function addRules(&$form, $paymentFields) {
239 foreach ($paymentFields as $paymentField => $fieldSpecs) {
240 if (!empty($fieldSpecs['rules'])) {
241 foreach ($fieldSpecs['rules'] as $rule) {
242 $form->addRule($paymentField,
243 $rule['rule_message'],
245 $rule['rule_parameters']
253 * Validate the payment instrument values before passing it to the payment processor.
255 * We want this to be able to be overridden by the payment processor, and default to using
256 * this object's validCreditCard for credit cards (implemented as the default in the Payment class).
258 * @param int $payment_processor_id
259 * @param array $values
260 * @param array $errors
261 * @param int $billing_profile_id
263 public static function validatePaymentInstrument($payment_processor_id, $values, &$errors, $billing_profile_id) {
264 $payment = Civi\Payment\System
::singleton()->getById($payment_processor_id);
265 $payment->setBillingProfile($billing_profile_id);
266 $payment->validatePaymentInstrument($values, $errors);
270 * Set default values for the form.
272 * @param CRM_Core_Form $form
273 * @param int $contactID
275 public static function setDefaultValues(&$form, $contactID) {
276 $billingDefaults = $form->getProfileDefaults('Billing', $contactID);
277 $form->_defaults
= array_merge($form->_defaults
, $billingDefaults);
279 // set default country & state from config if no country set
280 // note the effect of this is to set the billing country to default to the site default
281 // country if the person has an address but no country (for anonymous country is set above)
282 // this could have implications if the billing profile is filled but hidden.
283 // this behaviour has been in place for a while but the use of js to hide things has increased
284 if (empty($form->_defaults
["billing_country_id-{$form->_bltID}"])) {
285 $form->_defaults
["billing_country_id-{$form->_bltID}"] = CRM_Core_Config
::singleton()->defaultContactCountry
;
287 if (empty($form->_defaults
["billing_state_province_id-{$form->_bltID}"])) {
288 $form->_defaults
["billing_state_province_id-{$form->_bltID}"] = CRM_Core_Config
::singleton()
289 ->defaultContactStateProvince
;
294 * Make sure that credit card number and cvv are valid.
295 * Called within the scope of a QF formRule function
297 * @param array $values
298 * @param array $errors
299 * @param int $processorID
301 public static function validateCreditCard($values, &$errors, $processorID = NULL) {
302 if (!empty($values['credit_card_type']) ||
!empty($values['credit_card_number'])) {
303 if (!empty($values['credit_card_type'])) {
304 $processorCards = CRM_Financial_BAO_PaymentProcessor
::getCreditCards($processorID);
305 if (!empty($processorCards) && !in_array($values['credit_card_type'], $processorCards)) {
306 $errors['credit_card_type'] = ts('This processor does not support credit card type %1', [1 => $values['credit_card_type']]);
309 if (!empty($values['credit_card_number']) &&
310 !CRM_Utils_Rule
::creditCardNumber($values['credit_card_number'], $values['credit_card_type'])
312 $errors['credit_card_number'] = ts('Please enter a valid Card Number');
314 if (!empty($values['cvv2']) &&
315 !CRM_Utils_Rule
::cvv($values['cvv2'], $values['credit_card_type'])
317 $errors['cvv2'] = ts('Please enter a valid Card Verification Number');
323 * Map address fields.
328 * @param bool $reverse
330 public static function mapParams($id, $src, &$dst, $reverse = FALSE) {
332 'first_name' => 'billing_first_name',
333 'middle_name' => 'billing_middle_name',
334 'last_name' => 'billing_last_name',
335 'email' => "email-$id",
336 'street_address' => "billing_street_address-$id",
337 'supplemental_address_1' => "billing_supplemental_address_1-$id",
338 'city' => "billing_city-$id",
339 'state_province' => "billing_state_province-$id",
340 'postal_code' => "billing_postal_code-$id",
341 'country' => "billing_country-$id",
342 'contactID' => 'contact_id',
345 foreach ($map as $n => $v) {
347 if (isset($src[$n])) {
352 if (isset($src[$v])) {
358 //CRM-19469 provide option for returning modified params
363 * Get the credit card expiration month.
364 * The date format for this field should typically be "M Y" (ex: Feb 2011) or "m Y" (02 2011)
371 public static function getCreditCardExpirationMonth($src) {
372 if ($month = CRM_Utils_Array
::value('M', $src['credit_card_exp_date'])) {
376 return CRM_Utils_Array
::value('m', $src['credit_card_exp_date']);
380 * Get the credit card expiration year.
381 * The date format for this field should typically be "M Y" (ex: Feb 2011) or "m Y" (02 2011)
382 * This function exists only to make it consistent with getCreditCardExpirationMonth
388 public static function getCreditCardExpirationYear($src) {
389 return CRM_Utils_Array
::value('Y', $src['credit_card_exp_date']);
393 * Get the label for the processor.
395 * We do not use a label if there are no enterable fields.
397 * @param \CRM_Core_Payment $processor
401 public static function getPaymentLabel($processor) {
403 $paymentTypeLabel = self
::getPaymentTypeLabel($processor);
404 foreach (self
::getPaymentFieldMetadata(['object' => $processor]) as $paymentField) {
405 if ($paymentField['htmlType'] !== 'hidden') {
409 return $isVisible ?
$paymentTypeLabel : '';