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

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

woocommerce / includes Last commit date

class-wc-payment-gateways.php

489 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 array
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	// No wp_prime_option_caches needed: gateway settings are autoloaded (WC_Settings_API saves with autoload='yes').
95
96	// Get sort order option.
97	$ordering = (array) get_option( 'woocommerce_gateway_order' );
98	$order_end = 999;
99
100	// Load gateways in order.
101	foreach ( $load_gateways as $gateway ) {
102	if ( is_string( $gateway ) && class_exists( $gateway ) ) {
103	$gateway = new $gateway();
104	}
105
106	if ( is_a( $gateway, 'WC_Gateway_Paypal' ) ) {
107	WC_Gateway_Paypal::set_instance( $gateway );
108	if ( ! $this->should_load_paypal_standard() ) {
109	continue;
110	}
111	}
112
113	// Gateways need to be valid and extend WC_Payment_Gateway.
114	if ( ! is_a( $gateway, 'WC_Payment_Gateway' ) ) {
115	continue;
116	}
117
118	if ( isset( $ordering[ $gateway->id ] ) && is_numeric( $ordering[ $gateway->id ] ) ) {
119	// Add in position.
120	$this->payment_gateways[ $ordering[ $gateway->id ] ] = $gateway;
121	} else {
122	// Add to end of the array.
123	$this->payment_gateways[ $order_end ] = $gateway;
124	++$order_end;
125	}
126	}
127
128	ksort( $this->payment_gateways );
129
130	add_action( 'wc_payment_gateways_initialized', array( $this, 'on_payment_gateways_initialized' ) );
131	/**
132	* Hook that is called when the payment gateways have been initialized.
133	*
134	* @param WC_Payment_Gateways $wc_payment_gateways The payment gateways instance.
135	* @since 8.5.0
136	*/
137	do_action( 'wc_payment_gateways_initialized', $this );
138	}
139
140	// phpcs:disable Generic.CodeAnalysis.UnusedFunctionParameter.Found
141
142	/**
143	* Hook into payment gateway settings changes.
144	*
145	* @param WC_Payment_Gateways $wc_payment_gateways The WC_Payment_Gateways instance.
146	* @since 8.5.0
147	*
148	* @internal For exclusive usage of WooCommerce core, backwards compatibility not guaranteed.
149	*/
150	public function on_payment_gateways_initialized( WC_Payment_Gateways $wc_payment_gateways ) {
151	foreach ( $this->payment_gateways as $gateway ) {
152	$option_key = $gateway->get_option_key();
153	add_action(
154	'add_option_' . $option_key,
155	function ( $option, $value ) use ( $gateway ) {
156	$this->payment_gateway_settings_option_changed( $gateway, $value, $option );
157	},
158	10,
159	2
160	);
161	add_action(
162	'update_option_' . $option_key,
163	function ( $old_value, $value, $option ) use ( $gateway ) {
164	$this->payment_gateway_settings_option_changed( $gateway, $value, $option, $old_value );
165	},
166	10,
167	3
168	);
169	}
170	}
171
172	// phpcs:enable Generic.CodeAnalysis.UnusedFunctionParameter.Found
173
174	/**
175	* Callback for when a gateway settings option was added or updated.
176	*
177	* @param WC_Payment_Gateway $gateway The gateway for which the option was added or updated.
178	* @param mixed $value New value.
179	* @param string $option Option name.
180	* @param mixed $old_value Old value. `null` when called via add_option_ hook.
181	* @since 8.5.0
182	*/
183	private function payment_gateway_settings_option_changed( $gateway, $value, $option, $old_value = null ) {
184	if ( $this->was_gateway_enabled( $value, $old_value ) ) {
185	$logger = wc_get_container()->get( LegacyProxy::class )->call_function( 'wc_get_logger' );
186	$logger->info( sprintf( 'Payment gateway enabled: "%s"', $gateway->get_method_title() ) );
187
188	/**
189	* Fires when a payment gateway has been enabled.
190	*
191	* Used by WC_Email_Admin_Payment_Gateway_Enabled to send an admin notification email.
192	* This action is registered as a transactional email action in WC_Emails::init_transactional_emails(),
193	* which ensures WC_Emails is instantiated before the _notification variant is fired.
194	*
195	* @param WC_Payment_Gateway $gateway The gateway that was enabled.
196	*
197	* @since 10.7.0
198	*/
199	do_action( 'woocommerce_payment_gateway_enabled', $gateway );
200
201	// Track the gateway enable.
202	$this->record_gateway_event( 'enable', $gateway );
203	}
204
205	if ( $this->was_gateway_disabled( $value, $old_value ) ) {
206	// This is a change to a payment gateway's settings and it was just disabled. Let's track it.
207	$this->record_gateway_event( 'disable', $gateway );
208	}
209	}
210
211	/**
212	* Determines from changes in settings if a gateway was enabled.
213	*
214	* @param array $value New value.
215	* @param array $old_value Old value.
216	* @return bool Whether the gateway was enabled or not.
217	*/
218	private function was_gateway_enabled( $value, $old_value = null ) {
219	if ( null === $old_value ) {
220	// There was no old value, so this is a new option.
221	if ( ! empty( $value ) && is_array( $value ) && isset( $value['enabled'] ) && 'yes' === $value['enabled'] && isset( $value['title'] ) ) {
222	return true;
223	}
224	return false;
225	}
226	// There was an old value, so this is an update.
227	if (
228	ArrayUtil::get_value_or_default( $value, 'enabled' ) === 'yes' &&
229	ArrayUtil::get_value_or_default( $old_value, 'enabled' ) !== 'yes' ) {
230	return true;
231	}
232	return false;
233	}
234
235	/**
236	* Determines from changes in settings if a gateway was disabled.
237	*
238	* @param array $value New value.
239	* @param array $old_value Old value.
240	* @return bool Whether the gateway was disabled or not.
241	*/
242	private function was_gateway_disabled( $value, $old_value = null ) {
243	if ( null === $old_value ) {
244	// There was no old value, so this is a new option.
245	// We don't consider a new option for determining if a gateway was disabled.
246	return false;
247	}
248
249	// There was an old value, so this is an update.
250	if (
251	ArrayUtil::get_value_or_default( $value, 'enabled' ) === 'no' &&
252	ArrayUtil::get_value_or_default( $old_value, 'enabled' ) !== 'no' ) {
253	return true;
254	}
255
256	return false;
257	}
258
259	/**
260	* Get gateways.
261	*
262	* @return array
263	*/
264	public function payment_gateways() {
265	$_available_gateways = array();
266
267	if ( count( $this->payment_gateways ) > 0 ) {
268	foreach ( $this->payment_gateways as $gateway ) {
269	$_available_gateways[ $gateway->id ] = $gateway;
270	}
271	}
272
273	return $_available_gateways;
274	}
275
276	/**
277	* Get readable payment method name from payment method ID.
278	*
279	* Retrieves the payment gateway title from the payment method ID by loading
280	* the payment gateway instance.
281	*
282	* @param string $payment_gateway_id Payment method ID (e.g., "stripe", "paypal", "bacs").
283	* @return string Payment method name or ID if name not found.
284	*/
285	public function get_payment_gateway_name_by_id( string $payment_gateway_id ): string {
286	// Get available payment gateways.
287	$payment_gateways = $this->payment_gateways();
288
289	// Check if the payment method exists and has a title.
290	if ( isset( $payment_gateways[ $payment_gateway_id ] ) ) {
291	$gateway = $payment_gateways[ $payment_gateway_id ];
292	if ( is_object( $gateway ) && method_exists( $gateway, 'get_title' ) ) {
293	return $gateway->get_title();
294	} elseif ( is_object( $gateway ) && isset( $gateway->title ) ) {
295	return $gateway->title;
296	}
297	}
298
299	// Return the ID as fallback if no title found.
300	return $payment_gateway_id;
301	}
302
303	/**
304	* Get array of registered gateway ids
305	*
306	* @since 2.6.0
307	* @return array of strings
308	*/
309	public function get_payment_gateway_ids() {
310	return wp_list_pluck( $this->payment_gateways, 'id' );
311	}
312
313	/**
314	* Get available gateways for checkout.
315	*
316	* This should be used when displaying the available gateways/payment methods to the user,
317	* not in the WP admin or REST API contexts where there is no WC session.
318	* This is because the logic that hooks into the available gateways filter
319	* may try to rely on the existence of a WC session - a valid thing to do,
320	* and cause fatal errors when the session is not available.
321	*
322	* @return array The available payment gateways.
323	*/
324	public function get_available_payment_gateways() {
325	$_available_gateways = array();
326
327	foreach ( $this->payment_gateways as $gateway ) {
328	if ( $gateway->is_available() ) {
329	if ( ! is_add_payment_method_page() ) {
330	$_available_gateways[ $gateway->id ] = $gateway;
331	} elseif ( $gateway->supports( PaymentGatewayFeature::ADD_PAYMENT_METHOD ) \|\| $gateway->supports( PaymentGatewayFeature::TOKENIZATION ) ) {
332	$_available_gateways[ $gateway->id ] = $gateway;
333	}
334	}
335	}
336
337	return array_filter( (array) apply_filters( 'woocommerce_available_payment_gateways', $_available_gateways ), array( $this, 'filter_valid_gateway_class' ) );
338	}
339
340	/**
341	* Callback for array filter. Returns true if gateway is of correct type.
342	*
343	* @since 3.6.0
344	* @param object $gateway Gateway to check.
345	* @return bool
346	*/
347	protected function filter_valid_gateway_class( $gateway ) {
348	return $gateway && is_a( $gateway, 'WC_Payment_Gateway' );
349	}
350
351	/**
352	* Set the current, active gateway.
353	*
354	* @param array $gateways Available payment gateways.
355	*/
356	public function set_current_gateway( $gateways ) {
357	// Be on the defensive.
358	if ( ! is_array( $gateways ) \|\| empty( $gateways ) ) {
359	return;
360	}
361
362	$current_gateway = false;
363
364	if ( WC()->session ) {
365	$current = WC()->session->get( 'chosen_payment_method' );
366
367	if ( $current && isset( $gateways[ $current ] ) ) {
368	$current_gateway = $gateways[ $current ];
369	}
370	}
371
372	if ( ! $current_gateway ) {
373	$current_gateway = current( $gateways );
374	}
375
376	// Ensure we can make a call to set_current() without triggering an error.
377	if ( $current_gateway && is_callable( array( $current_gateway, 'set_current' ) ) ) {
378	$current_gateway->set_current();
379	}
380	}
381
382	/**
383	* Save options in admin.
384	*/
385	public function process_admin_options() {
386	$gateway_order = isset( $_POST['gateway_order'] ) ? wc_clean( wp_unslash( $_POST['gateway_order'] ) ) : ''; // WPCS: input var ok, CSRF ok.
387	$order = array();
388
389	if ( is_array( $gateway_order ) && count( $gateway_order ) > 0 ) {
390	$loop = 0;
391	foreach ( $gateway_order as $gateway_id ) {
392	$order[ esc_attr( $gateway_id ) ] = $loop;
393	++$loop;
394	}
395	}
396
397	update_option( 'woocommerce_gateway_order', $order );
398	}
399
400	/**
401	* Determines if PayPal Standard should be loaded.
402	*
403	* @since 5.5.0
404	* @return bool Whether PayPal Standard should be loaded or not.
405	*/
406	protected function should_load_paypal_standard() {
407	$paypal = WC_Gateway_Paypal::get_instance();
408	return $paypal->should_load();
409	}
410
411	/**
412	* Send a Tracks event.
413	*
414	* By default, Woo adds `url`, `blog_lang`, `blog_id`, `store_id`, `products_count`, and `wc_version`
415	* properties to every event.
416	*
417	* @param string $name The event name.
418	* If it is not prefixed, it will be with the standard prefix.
419	* @param WC_Payment_Gateway $gateway The payment gateway object.
420	*
421	* @return void
422	*/
423	private function record_gateway_event( string $name, $gateway ) {
424	if ( ! function_exists( 'wc_admin_record_tracks_event' ) ) {
425	return;
426	}
427
428	if ( ! is_a( $gateway, 'WC_Payment_Gateway' ) ) {
429	// If the gateway is not a valid payment gateway, we don't record the event.
430	return;
431	}
432
433	// If the event name is empty, we don't record it.
434	if ( empty( $name ) ) {
435	return;
436	}
437
438	// If the event name is not prefixed, we prefix it.
439	$prefix = SettingsPaymentsService::EVENT_PREFIX . 'provider_';
440	if ( ! str_starts_with( $name, $prefix ) ) {
441	$name = $prefix . $name;
442	}
443
444	$properties = array(
445	'provider_id' => $gateway->id,
446	'business_country' => WC()->countries->get_base_country(),
447	);
448
449	try {
450	/**
451	* The Payments Settings [page] service.
452	*
453	* @var SettingsPaymentsService $settings_payments_service
454	*/
455	$settings_payments_service = wc_get_container()->get( SettingsPaymentsService::class );
456	// Get the business country from the Payments Settings service.
457	$properties['business_country'] = $settings_payments_service->get_country();
458
459	/**
460	* The Payments Providers service.
461	*
462	* @var PaymentsProviders $payments_providers_service
463	*/
464	$payments_providers_service = wc_get_container()->get( PaymentsProviders::class );
465
466	$gateway_details = $payments_providers_service->get_payment_gateway_details( $gateway, 0, $properties['business_country'] );
467	// If the gateway details have a suggestion ID, we add it to the properties.
468	if ( ! empty( $gateway_details['_suggestion_id'] ) ) {
469	$properties['suggestion_id'] = $gateway_details['_suggestion_id'];
470	}
471	if ( ! empty( $gateway_details['plugin']['slug'] ) ) {
472	$properties['provider_extension_slug'] = $gateway_details['plugin']['slug'];
473	}
474	} catch ( \Throwable $e ) {
475	// Do nothing but log so we can investigate.
476	SafeGlobalFunctionProxy::wc_get_logger()->debug(
477	'Failed to gather provider-specific details for gateway: ' . $e->getMessage(),
478	array(
479	'gateway' => $gateway->id,
480	'source' => 'settings-payments',
481	'exception' => $e,
482	)
483	);
484	}
485
486	wc_admin_record_tracks_event( $name, $properties );
487	}
488	}
489