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

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

woocommerce / includes Last commit date

class-wc-payment-gateways.php

498 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 ( $this->was_gateway_enabled( $value, $old_value ) ) {
194	$logger = wc_get_container()->get( LegacyProxy::class )->call_function( 'wc_get_logger' );
195	$logger->info( sprintf( 'Payment gateway enabled: "%s"', $gateway->get_method_title() ) );
196
197	/**
198	* Fires when a payment gateway has been enabled.
199	*
200	* Used by WC_Email_Admin_Payment_Gateway_Enabled to send an admin notification email.
201	* This action is registered as a transactional email action in WC_Emails::init_transactional_emails(),
202	* which ensures WC_Emails is instantiated before the _notification variant is fired.
203	*
204	* @param WC_Payment_Gateway $gateway The gateway that was enabled.
205	*
206	* @since 10.7.0
207	*/
208	do_action( 'woocommerce_payment_gateway_enabled', $gateway );
209
210	// Track the gateway enable.
211	$this->record_gateway_event( 'enable', $gateway );
212	}
213
214	if ( $this->was_gateway_disabled( $value, $old_value ) ) {
215	// This is a change to a payment gateway's settings and it was just disabled. Let's track it.
216	$this->record_gateway_event( 'disable', $gateway );
217	}
218	}
219
220	/**
221	* Determines from changes in settings if a gateway was enabled.
222	*
223	* @param array $value New value.
224	* @param array $old_value Old value.
225	* @return bool Whether the gateway was enabled or not.
226	*/
227	private function was_gateway_enabled( $value, $old_value = null ) {
228	if ( null === $old_value ) {
229	// There was no old value, so this is a new option.
230	if ( ! empty( $value ) && is_array( $value ) && isset( $value['enabled'] ) && 'yes' === $value['enabled'] && isset( $value['title'] ) ) {
231	return true;
232	}
233	return false;
234	}
235	// There was an old value, so this is an update.
236	if (
237	ArrayUtil::get_value_or_default( $value, 'enabled' ) === 'yes' &&
238	ArrayUtil::get_value_or_default( $old_value, 'enabled' ) !== 'yes' ) {
239	return true;
240	}
241	return false;
242	}
243
244	/**
245	* Determines from changes in settings if a gateway was disabled.
246	*
247	* @param array $value New value.
248	* @param array $old_value Old value.
249	* @return bool Whether the gateway was disabled or not.
250	*/
251	private function was_gateway_disabled( $value, $old_value = null ) {
252	if ( null === $old_value ) {
253	// There was no old value, so this is a new option.
254	// We don't consider a new option for determining if a gateway was disabled.
255	return false;
256	}
257
258	// There was an old value, so this is an update.
259	if (
260	ArrayUtil::get_value_or_default( $value, 'enabled' ) === 'no' &&
261	ArrayUtil::get_value_or_default( $old_value, 'enabled' ) !== 'no' ) {
262	return true;
263	}
264
265	return false;
266	}
267
268	/**
269	* Get gateways.
270	*
271	* @return array
272	*/
273	public function payment_gateways() {
274	$_available_gateways = array();
275
276	if ( count( $this->payment_gateways ) > 0 ) {
277	foreach ( $this->payment_gateways as $gateway ) {
278	$_available_gateways[ $gateway->id ] = $gateway;
279	}
280	}
281
282	return $_available_gateways;
283	}
284
285	/**
286	* Get readable payment method name from payment method ID.
287	*
288	* Retrieves the payment gateway title from the payment method ID by loading
289	* the payment gateway instance.
290	*
291	* @param string $payment_gateway_id Payment method ID (e.g., "stripe", "paypal", "bacs").
292	* @return string Payment method name or ID if name not found.
293	*/
294	public function get_payment_gateway_name_by_id( string $payment_gateway_id ): string {
295	// Get available payment gateways.
296	$payment_gateways = $this->payment_gateways();
297
298	// Check if the payment method exists and has a title.
299	if ( isset( $payment_gateways[ $payment_gateway_id ] ) ) {
300	$gateway = $payment_gateways[ $payment_gateway_id ];
301	if ( is_object( $gateway ) && method_exists( $gateway, 'get_title' ) ) {
302	return $gateway->get_title();
303	} elseif ( is_object( $gateway ) && isset( $gateway->title ) ) {
304	return $gateway->title;
305	}
306	}
307
308	// Return the ID as fallback if no title found.
309	return $payment_gateway_id;
310	}
311
312	/**
313	* Get array of registered gateway ids
314	*
315	* @since 2.6.0
316	* @return array of strings
317	*/
318	public function get_payment_gateway_ids() {
319	return wp_list_pluck( $this->payment_gateways, 'id' );
320	}
321
322	/**
323	* Get available gateways for checkout.
324	*
325	* This should be used when displaying the available gateways/payment methods to the user,
326	* not in the WP admin or REST API contexts where there is no WC session.
327	* This is because the logic that hooks into the available gateways filter
328	* may try to rely on the existence of a WC session - a valid thing to do,
329	* and cause fatal errors when the session is not available.
330	*
331	* @return WC_Payment_Gateway[] The available payment gateways.
332	*/
333	public function get_available_payment_gateways() {
334	$_available_gateways = array();
335
336	foreach ( $this->payment_gateways as $gateway ) {
337	if ( $gateway->is_available() ) {
338	if ( ! is_add_payment_method_page() ) {
339	$_available_gateways[ $gateway->id ] = $gateway;
340	} elseif ( $gateway->supports( PaymentGatewayFeature::ADD_PAYMENT_METHOD ) \|\| $gateway->supports( PaymentGatewayFeature::TOKENIZATION ) ) {
341	$_available_gateways[ $gateway->id ] = $gateway;
342	}
343	}
344	}
345
346	return array_filter( (array) apply_filters( 'woocommerce_available_payment_gateways', $_available_gateways ), array( $this, 'filter_valid_gateway_class' ) );
347	}
348
349	/**
350	* Callback for array filter. Returns true if gateway is of correct type.
351	*
352	* @since 3.6.0
353	* @param object $gateway Gateway to check.
354	* @return bool
355	*/
356	protected function filter_valid_gateway_class( $gateway ) {
357	return $gateway && is_a( $gateway, 'WC_Payment_Gateway' );
358	}
359
360	/**
361	* Set the current, active gateway.
362	*
363	* @param array $gateways Available payment gateways.
364	*/
365	public function set_current_gateway( $gateways ) {
366	// Be on the defensive.
367	if ( ! is_array( $gateways ) \|\| empty( $gateways ) ) {
368	return;
369	}
370
371	$current_gateway = false;
372
373	if ( WC()->session ) {
374	$current = WC()->session->get( 'chosen_payment_method' );
375
376	if ( $current && isset( $gateways[ $current ] ) ) {
377	$current_gateway = $gateways[ $current ];
378	}
379	}
380
381	if ( ! $current_gateway ) {
382	$current_gateway = current( $gateways );
383	}
384
385	// Ensure we can make a call to set_current() without triggering an error.
386	if ( $current_gateway && is_callable( array( $current_gateway, 'set_current' ) ) ) {
387	$current_gateway->set_current();
388	}
389	}
390
391	/**
392	* Save options in admin.
393	*/
394	public function process_admin_options() {
395	$gateway_order = isset( $_POST['gateway_order'] ) ? wc_clean( wp_unslash( $_POST['gateway_order'] ) ) : ''; // WPCS: input var ok, CSRF ok.
396	$order = array();
397
398	if ( is_array( $gateway_order ) && count( $gateway_order ) > 0 ) {
399	$loop = 0;
400	foreach ( $gateway_order as $gateway_id ) {
401	$order[ esc_attr( $gateway_id ) ] = $loop;
402	++$loop;
403	}
404	}
405
406	update_option( 'woocommerce_gateway_order', $order );
407	}
408
409	/**
410	* Determines if PayPal Standard should be loaded.
411	*
412	* @since 5.5.0
413	* @return bool Whether PayPal Standard should be loaded or not.
414	*/
415	protected function should_load_paypal_standard() {
416	$paypal = WC_Gateway_Paypal::get_instance();
417	return $paypal->should_load();
418	}
419
420	/**
421	* Send a Tracks event.
422	*
423	* By default, Woo adds `url`, `blog_lang`, `blog_id`, `store_id`, `products_count`, and `wc_version`
424	* properties to every event.
425	*
426	* @param string $name The event name.
427	* If it is not prefixed, it will be with the standard prefix.
428	* @param WC_Payment_Gateway $gateway The payment gateway object.
429	*
430	* @return void
431	*/
432	private function record_gateway_event( string $name, $gateway ) {
433	if ( ! function_exists( 'wc_admin_record_tracks_event' ) ) {
434	return;
435	}
436
437	if ( ! is_a( $gateway, 'WC_Payment_Gateway' ) ) {
438	// If the gateway is not a valid payment gateway, we don't record the event.
439	return;
440	}
441
442	// If the event name is empty, we don't record it.
443	if ( empty( $name ) ) {
444	return;
445	}
446
447	// If the event name is not prefixed, we prefix it.
448	$prefix = SettingsPaymentsService::EVENT_PREFIX . 'provider_';
449	if ( ! str_starts_with( $name, $prefix ) ) {
450	$name = $prefix . $name;
451	}
452
453	$properties = array(
454	'provider_id' => $gateway->id,
455	'business_country' => WC()->countries->get_base_country(),
456	);
457
458	try {
459	/**
460	* The Payments Settings [page] service.
461	*
462	* @var SettingsPaymentsService $settings_payments_service
463	*/
464	$settings_payments_service = wc_get_container()->get( SettingsPaymentsService::class );
465	// Get the business country from the Payments Settings service.
466	$properties['business_country'] = $settings_payments_service->get_country();
467
468	/**
469	* The Payments Providers service.
470	*
471	* @var PaymentsProviders $payments_providers_service
472	*/
473	$payments_providers_service = wc_get_container()->get( PaymentsProviders::class );
474
475	$gateway_details = $payments_providers_service->get_payment_gateway_details( $gateway, 0, $properties['business_country'] );
476	// If the gateway details have a suggestion ID, we add it to the properties.
477	if ( ! empty( $gateway_details['_suggestion_id'] ) ) {
478	$properties['suggestion_id'] = $gateway_details['_suggestion_id'];
479	}
480	if ( ! empty( $gateway_details['plugin']['slug'] ) ) {
481	$properties['provider_extension_slug'] = $gateway_details['plugin']['slug'];
482	}
483	} catch ( \Throwable $e ) {
484	// Do nothing but log so we can investigate.
485	SafeGlobalFunctionProxy::wc_get_logger()->debug(
486	'Failed to gather provider-specific details for gateway: ' . $e->getMessage(),
487	array(
488	'gateway' => $gateway->id,
489	'source' => 'settings-payments',
490	'exception' => $e,
491	)
492	);
493	}
494
495	wc_admin_record_tracks_event( $name, $properties );
496	}
497	}
498