class-wc-payment-gateways.php — WooCommerce 11.1.0

woocommerce / includes / class-wc-payment-gateways.php

woocommerce / includes Last commit date

class-wc-payment-gateways.php

540 lines

1	<?php
2	/**
3	* WooCommerce Payment Gateways
4	*
5	* Loads payment gateways via hooks for use in the store.
6	*
7	* @version 2.2.0
8	* @package WooCommerce\Classes\Payment
9	*/
10
11	use Automattic\WooCommerce\Enums\PaymentGatewayFeature;
12	use Automattic\WooCommerce\Internal\Admin\Settings\Payments as SettingsPaymentsService;
13	use Automattic\WooCommerce\Internal\Admin\Settings\PaymentsProviders;
14	use Automattic\WooCommerce\Internal\Logging\SafeGlobalFunctionProxy;
15	use Automattic\WooCommerce\Proxies\LegacyProxy;
16	use Automattic\WooCommerce\Utilities\ArrayUtil;
17
18	defined( 'ABSPATH' ) \|\| exit;
19
20	/**
21	* Payment gateways class.
22	*/
23	class WC_Payment_Gateways {
24
25	/**
26	* Payment gateway classes.
27	*
28	* @var WC_Payment_Gateway[]
29	*/
30	public $payment_gateways = array();
31
32	/**
33	* The single instance of the class.
34	*
35	* @var WC_Payment_Gateways
36	* @since 2.1.0
37	*/
38	protected static $_instance = null;
39
40	/**
41	* Main WC_Payment_Gateways Instance.
42	*
43	* Ensures only one instance of WC_Payment_Gateways is loaded or can be loaded.
44	*
45	* @since 2.1
46	* @return WC_Payment_Gateways Main instance
47	*/
48	public static function instance() {
49	if ( is_null( self::$_instance ) ) {
50	self::$_instance = new self();
51	}
52	return self::$_instance;
53	}
54
55	/**
56	* Cloning is forbidden.
57	*
58	* @since 2.1
59	*/
60	public function __clone() {
61	wc_doing_it_wrong( __FUNCTION__, __( 'Cloning is forbidden.', 'woocommerce' ), '2.1' );
62	}
63
64	/**
65	* Unserializing instances of this class is forbidden.
66	*
67	* @since 2.1
68	*/
69	public function __wakeup() {
70	wc_doing_it_wrong( __FUNCTION__, __( 'Unserializing instances of this class is forbidden.', 'woocommerce' ), '2.1' );
71	}
72
73	/**
74	* Initialize payment gateways.
75	*/
76	public function __construct() {
77	$this->init();
78	}
79
80	/**
81	* Load gateways and hook in functions.
82	*/
83	public function init() {
84	$load_gateways = array(
85	'WC_Gateway_BACS',
86	'WC_Gateway_Cheque',
87	'WC_Gateway_COD',
88	'WC_Gateway_Paypal',
89	);
90
91	// Filter.
92	$load_gateways = apply_filters( 'woocommerce_payment_gateways', $load_gateways );
93
94	// Preload option caches to minimize future queries for options that do not yet exist or are not set to autoload.
95	wp_prime_option_caches(
96	array(
97	'woocommerce_bacs_settings',
98	'woocommerce_bacs_accounts',
99	'woocommerce_cheque_settings',
100	'woocommerce_cod_settings',
101	'woocommerce_paypal_settings',
102	)
103	);
104
105	// Get sort order option.
106	$ordering = (array) get_option( 'woocommerce_gateway_order' );
107	$order_end = 999;
108
109	// Load gateways in order.
110	foreach ( $load_gateways as $gateway ) {
111	if ( is_string( $gateway ) && class_exists( $gateway ) ) {
112	$gateway = new $gateway();
113	}
114
115	if ( is_a( $gateway, 'WC_Gateway_Paypal' ) ) {
116	WC_Gateway_Paypal::set_instance( $gateway );
117	if ( ! $this->should_load_paypal_standard() ) {
118	continue;
119	}
120	}
121
122	// Gateways need to be valid and extend WC_Payment_Gateway.
123	if ( ! is_a( $gateway, 'WC_Payment_Gateway' ) ) {
124	continue;
125	}
126
127	if ( isset( $ordering[ $gateway->id ] ) && is_numeric( $ordering[ $gateway->id ] ) ) {
128	// Add in position.
129	$this->payment_gateways[ $ordering[ $gateway->id ] ] = $gateway;
130	} else {
131	// Add to end of the array.
132	$this->payment_gateways[ $order_end ] = $gateway;
133	++$order_end;
134	}
135	}
136
137	ksort( $this->payment_gateways );
138
139	add_action( 'wc_payment_gateways_initialized', array( $this, 'on_payment_gateways_initialized' ) );
140	/**
141	* Hook that is called when the payment gateways have been initialized.
142	*
143	* @param WC_Payment_Gateways $wc_payment_gateways The payment gateways instance.
144	* @since 8.5.0
145	*/
146	do_action( 'wc_payment_gateways_initialized', $this );
147	}
148
149	// phpcs:disable Generic.CodeAnalysis.UnusedFunctionParameter.Found
150
151	/**
152	* Hook into payment gateway settings changes.
153	*
154	* @param WC_Payment_Gateways $wc_payment_gateways The WC_Payment_Gateways instance.
155	* @since 8.5.0
156	*
157	* @internal For exclusive usage of WooCommerce core, backwards compatibility not guaranteed.
158	*/
159	public function on_payment_gateways_initialized( WC_Payment_Gateways $wc_payment_gateways ) {
160	foreach ( $this->payment_gateways as $gateway ) {
161	$option_key = $gateway->get_option_key();
162	add_action(
163	'add_option_' . $option_key,
164	function ( $option, $value ) use ( $gateway ) {
165	$this->payment_gateway_settings_option_changed( $gateway, $value, $option );
166	},
167	10,
168	2
169	);
170	add_action(
171	'update_option_' . $option_key,
172	function ( $old_value, $value, $option ) use ( $gateway ) {
173	$this->payment_gateway_settings_option_changed( $gateway, $value, $option, $old_value );
174	},
175	10,
176	3
177	);
178	}
179	}
180
181	// phpcs:enable Generic.CodeAnalysis.UnusedFunctionParameter.Found
182
183	/**
184	* Callback for when a gateway settings option was added or updated.
185	*
186	* @param WC_Payment_Gateway $gateway The gateway for which the option was added or updated.
187	* @param mixed $value New value.
188	* @param string $option Option name.
189	* @param mixed $old_value Old value. `null` when called via add_option_ hook.
190	* @since 8.5.0
191	*/
192	private function payment_gateway_settings_option_changed( $gateway, $value, $option, $old_value = null ) {
193	if ( ! is_array( $value ) \|\| ( null !== $old_value && ! is_array( $old_value ) ) ) {
194	$logger = wc_get_container()->get( LegacyProxy::class )->call_function( 'wc_get_logger' );
195
196	if ( ! is_array( $value ) ) {
197	$logger->warning(
198	sprintf( 'New payment gateway settings for "%s" were not an array; using gateway defaults for transition handling.', $option ),
199	array( 'source' => 'payment-gateways' )
200	);
201	}
202
203	if ( null !== $old_value && ! is_array( $old_value ) ) {
204	$logger->warning(
205	sprintf( 'Previous payment gateway settings for "%s" were not an array; using gateway defaults for transition handling.', $option ),
206	array( 'source' => 'payment-gateways' )
207	);
208	}
209
210	$value = $this->normalize_gateway_settings_for_transition( $gateway, $value );
211	if ( null !== $old_value ) {
212	$old_value = $this->normalize_gateway_settings_for_transition( $gateway, $old_value );
213	}
214	}
215
216	if ( $this->was_gateway_enabled( $value, $old_value ) ) {
217	$logger = wc_get_container()->get( LegacyProxy::class )->call_function( 'wc_get_logger' );
218	$logger->info( sprintf( 'Payment gateway enabled: "%s"', $gateway->get_method_title() ) );
219
220	/**
221	* Fires when a payment gateway has been enabled.
222	*
223	* Used by WC_Email_Admin_Payment_Gateway_Enabled to send an admin notification email.
224	* This action is registered as a transactional email action in WC_Emails::init_transactional_emails(),
225	* which ensures WC_Emails is instantiated before the _notification variant is fired.
226	*
227	* @param WC_Payment_Gateway $gateway The gateway that was enabled.
228	*
229	* @since 10.7.0
230	*/
231	do_action( 'woocommerce_payment_gateway_enabled', $gateway );
232
233	// Track the gateway enable.
234	$this->record_gateway_event( 'enable', $gateway );
235	}
236
237	if ( $this->was_gateway_disabled( $value, $old_value ) ) {
238	// This is a change to a payment gateway's settings and it was just disabled. Let's track it.
239	$this->record_gateway_event( 'disable', $gateway );
240	}
241	}
242
243	/**
244	* Normalize gateway settings for transition handling.
245	*
246	* @param WC_Payment_Gateway $gateway Payment gateway.
247	* @param mixed $settings Gateway settings.
248	* @return array Normalized gateway settings.
249	*/
250	private function normalize_gateway_settings_for_transition( $gateway, $settings ) {
251	if ( is_array( $settings ) ) {
252	return $settings;
253	}
254
255	$form_fields = $gateway->get_form_fields();
256	$enabled_field = $form_fields['enabled'] ?? array();
257	$enabled_default = $gateway->get_field_default( $enabled_field );
258
259	return array( 'enabled' => 'yes' === $enabled_default ? 'yes' : 'no' );
260	}
261
262	/**
263	* Determines from changes in settings if a gateway was enabled.
264	*
265	* @param array $value New value.
266	* @param array $old_value Old value.
267	* @return bool Whether the gateway was enabled or not.
268	*/
269	private function was_gateway_enabled( $value, $old_value = null ) {
270	if ( null === $old_value ) {
271	// There was no old value, so this is a new option.
272	if ( ! empty( $value ) && is_array( $value ) && isset( $value['enabled'] ) && 'yes' === $value['enabled'] && isset( $value['title'] ) ) {
273	return true;
274	}
275	return false;
276	}
277	// There was an old value, so this is an update.
278	if (
279	ArrayUtil::get_value_or_default( $value, 'enabled' ) === 'yes' &&
280	ArrayUtil::get_value_or_default( $old_value, 'enabled' ) !== 'yes' ) {
281	return true;
282	}
283	return false;
284	}
285
286	/**
287	* Determines from changes in settings if a gateway was disabled.
288	*
289	* @param array $value New value.
290	* @param array $old_value Old value.
291	* @return bool Whether the gateway was disabled or not.
292	*/
293	private function was_gateway_disabled( $value, $old_value = null ) {
294	if ( null === $old_value ) {
295	// There was no old value, so this is a new option.
296	// We don't consider a new option for determining if a gateway was disabled.
297	return false;
298	}
299
300	// There was an old value, so this is an update.
301	if (
302	ArrayUtil::get_value_or_default( $value, 'enabled' ) === 'no' &&
303	ArrayUtil::get_value_or_default( $old_value, 'enabled' ) !== 'no' ) {
304	return true;
305	}
306
307	return false;
308	}
309
310	/**
311	* Get gateways.
312	*
313	* @return array
314	*/
315	public function payment_gateways() {
316	$_available_gateways = array();
317
318	if ( count( $this->payment_gateways ) > 0 ) {
319	foreach ( $this->payment_gateways as $gateway ) {
320	$_available_gateways[ $gateway->id ] = $gateway;
321	}
322	}
323
324	return $_available_gateways;
325	}
326
327	/**
328	* Get readable payment method name from payment method ID.
329	*
330	* Retrieves the payment gateway title from the payment method ID by loading
331	* the payment gateway instance.
332	*
333	* @param string $payment_gateway_id Payment method ID (e.g., "stripe", "paypal", "bacs").
334	* @return string Payment method name or ID if name not found.
335	*/
336	public function get_payment_gateway_name_by_id( string $payment_gateway_id ): string {
337	// Get available payment gateways.
338	$payment_gateways = $this->payment_gateways();
339
340	// Check if the payment method exists and has a title.
341	if ( isset( $payment_gateways[ $payment_gateway_id ] ) ) {
342	$gateway = $payment_gateways[ $payment_gateway_id ];
343	if ( is_object( $gateway ) && method_exists( $gateway, 'get_title' ) ) {
344	return $gateway->get_title();
345	} elseif ( is_object( $gateway ) && isset( $gateway->title ) ) {
346	return $gateway->title;
347	}
348	}
349
350	// Return the ID as fallback if no title found.
351	return $payment_gateway_id;
352	}
353
354	/**
355	* Get array of registered gateway ids
356	*
357	* @since 2.6.0
358	* @return array of strings
359	*/
360	public function get_payment_gateway_ids() {
361	return wp_list_pluck( $this->payment_gateways, 'id' );
362	}
363
364	/**
365	* Get available gateways for checkout.
366	*
367	* This should be used when displaying the available gateways/payment methods to the user,
368	* not in the WP admin or REST API contexts where there is no WC session.
369	* This is because the logic that hooks into the available gateways filter
370	* may try to rely on the existence of a WC session - a valid thing to do,
371	* and cause fatal errors when the session is not available.
372	*
373	* @return WC_Payment_Gateway[] The available payment gateways.
374	*/
375	public function get_available_payment_gateways() {
376	$_available_gateways = array();
377
378	foreach ( $this->payment_gateways as $gateway ) {
379	if ( $gateway->is_available() ) {
380	if ( ! is_add_payment_method_page() ) {
381	$_available_gateways[ $gateway->id ] = $gateway;
382	} elseif ( $gateway->supports( PaymentGatewayFeature::ADD_PAYMENT_METHOD ) \|\| $gateway->supports( PaymentGatewayFeature::TOKENIZATION ) ) {
383	$_available_gateways[ $gateway->id ] = $gateway;
384	}
385	}
386	}
387
388	return array_filter( (array) apply_filters( 'woocommerce_available_payment_gateways', $_available_gateways ), array( $this, 'filter_valid_gateway_class' ) );
389	}
390
391	/**
392	* Callback for array filter. Returns true if gateway is of correct type.
393	*
394	* @since 3.6.0
395	* @param object $gateway Gateway to check.
396	* @return bool
397	*/
398	protected function filter_valid_gateway_class( $gateway ) {
399	return $gateway && is_a( $gateway, 'WC_Payment_Gateway' );
400	}
401
402	/**
403	* Set the current, active gateway.
404	*
405	* @param array $gateways Available payment gateways.
406	*/
407	public function set_current_gateway( $gateways ) {
408	// Be on the defensive.
409	if ( ! is_array( $gateways ) \|\| empty( $gateways ) ) {
410	return;
411	}
412
413	$current_gateway = false;
414
415	if ( WC()->session ) {
416	$current = WC()->session->get( 'chosen_payment_method' );
417
418	if ( $current && isset( $gateways[ $current ] ) ) {
419	$current_gateway = $gateways[ $current ];
420	}
421	}
422
423	if ( ! $current_gateway ) {
424	$current_gateway = current( $gateways );
425	}
426
427	// Ensure we can make a call to set_current() without triggering an error.
428	if ( $current_gateway && is_callable( array( $current_gateway, 'set_current' ) ) ) {
429	$current_gateway->set_current();
430	}
431	}
432
433	/**
434	* Save options in admin.
435	*/
436	public function process_admin_options() {
437	$gateway_order = isset( $_POST['gateway_order'] ) ? wc_clean( wp_unslash( $_POST['gateway_order'] ) ) : ''; // WPCS: input var ok, CSRF ok.
438	$order = array();
439
440	if ( is_array( $gateway_order ) && count( $gateway_order ) > 0 ) {
441	$loop = 0;
442	foreach ( $gateway_order as $gateway_id ) {
443	$order[ esc_attr( $gateway_id ) ] = $loop;
444	++$loop;
445	}
446	}
447
448	update_option( 'woocommerce_gateway_order', $order );
449	}
450
451	/**
452	* Determines if PayPal Standard should be loaded.
453	*
454	* @since 5.5.0
455	* @return bool Whether PayPal Standard should be loaded or not.
456	*/
457	protected function should_load_paypal_standard() {
458	$paypal = WC_Gateway_Paypal::get_instance();
459	return $paypal->should_load();
460	}
461
462	/**
463	* Send a Tracks event.
464	*
465	* By default, Woo adds `url`, `blog_lang`, `blog_id`, `store_id`, `products_count`, and `wc_version`
466	* properties to every event.
467	*
468	* @param string $name The event name.
469	* If it is not prefixed, it will be with the standard prefix.
470	* @param WC_Payment_Gateway $gateway The payment gateway object.
471	*
472	* @return void
473	*/
474	private function record_gateway_event( string $name, $gateway ) {
475	if ( ! function_exists( 'wc_admin_record_tracks_event' ) ) {
476	return;
477	}
478
479	if ( ! is_a( $gateway, 'WC_Payment_Gateway' ) ) {
480	// If the gateway is not a valid payment gateway, we don't record the event.
481	return;
482	}
483
484	// If the event name is empty, we don't record it.
485	if ( empty( $name ) ) {
486	return;
487	}
488
489	// If the event name is not prefixed, we prefix it.
490	$prefix = SettingsPaymentsService::EVENT_PREFIX . 'provider_';
491	if ( ! str_starts_with( $name, $prefix ) ) {
492	$name = $prefix . $name;
493	}
494
495	$properties = array(
496	'provider_id' => $gateway->id,
497	'business_country' => WC()->countries->get_base_country(),
498	);
499
500	try {
501	/**
502	* The Payments Settings [page] service.
503	*
504	* @var SettingsPaymentsService $settings_payments_service
505	*/
506	$settings_payments_service = wc_get_container()->get( SettingsPaymentsService::class );
507	// Get the business country from the Payments Settings service.
508	$properties['business_country'] = $settings_payments_service->get_country();
509
510	/**
511	* The Payments Providers service.
512	*
513	* @var PaymentsProviders $payments_providers_service
514	*/
515	$payments_providers_service = wc_get_container()->get( PaymentsProviders::class );
516
517	$gateway_details = $payments_providers_service->get_payment_gateway_details( $gateway, 0, $properties['business_country'] );
518	// If the gateway details have a suggestion ID, we add it to the properties.
519	if ( ! empty( $gateway_details['_suggestion_id'] ) ) {
520	$properties['suggestion_id'] = $gateway_details['_suggestion_id'];
521	}
522	if ( ! empty( $gateway_details['plugin']['slug'] ) ) {
523	$properties['provider_extension_slug'] = $gateway_details['plugin']['slug'];
524	}
525	} catch ( \Throwable $e ) {
526	// Do nothing but log so we can investigate.
527	SafeGlobalFunctionProxy::wc_get_logger()->debug(
528	'Failed to gather provider-specific details for gateway: ' . $e->getMessage(),
529	array(
530	'gateway' => $gateway->id,
531	'source' => 'settings-payments',
532	'exception' => $e,
533	)
534	);
535	}
536
537	wc_admin_record_tracks_event( $name, $properties );
538	}
539	}
540