OrderAttributionController.php — WooCommerce 10.9.3

woocommerce / src / Internal / Orders / OrderAttributionController.php

woocommerce / src / Internal / Orders Last commit date

CardIcons 1 year ago CouponsController.php 7 months ago IppFunctions.php 1 year ago MobileMessagingHandler.php 2 years ago OrderActionsRestController.php 3 months ago OrderAttributionBlocksController.php 1 year ago OrderAttributionController.php 5 months ago OrderNoteGroup.php 3 months ago OrderStatusRestController.php 5 months ago PaymentInfo.php 10 months ago PointOfSaleEmailHandler.php 3 months ago PointOfSaleOrderUtil.php 4 weeks ago TaxesController.php 3 years ago

OrderAttributionController.php

596 lines

1	<?php
2	declare( strict_types=1 );
3
4	namespace Automattic\WooCommerce\Internal\Orders;
5
6	use Automattic\Jetpack\Constants;
7	use Automattic\WooCommerce\Internal\Features\FeaturesController;
8	use Automattic\WooCommerce\Internal\Integrations\WPConsentAPI;
9	use Automattic\WooCommerce\Internal\RegisterHooksInterface;
10	use Automattic\WooCommerce\Internal\Traits\ScriptDebug;
11	use Automattic\WooCommerce\Internal\Traits\OrderAttributionMeta;
12	use Automattic\WooCommerce\Proxies\LegacyProxy;
13	use Automattic\WooCommerce\Utilities\OrderUtil;
14	use Exception;
15	use WC_Customer;
16	use WC_Log_Levels;
17	use WC_Logger_Interface;
18	use WC_Order;
19
20	/**
21	* Class OrderAttributionController
22	*
23	* @since 8.5.0
24	*/
25	class OrderAttributionController implements RegisterHooksInterface {
26
27	use ScriptDebug;
28	use OrderAttributionMeta {
29	get_prefixed_field_name as public;
30	}
31
32	/**
33	* The WPConsentAPI integration instance.
34	*
35	* @var WPConsentAPI
36	*/
37	private $consent;
38
39	/**
40	* The FeatureController instance.
41	*
42	* @var FeaturesController
43	*/
44	private $feature_controller;
45
46	/**
47	* WooCommerce logger class instance.
48	*
49	* @var WC_Logger_Interface
50	*/
51	private $logger;
52
53	/**
54	* The LegacyProxy instance.
55	*
56	* @var LegacyProxy
57	*/
58	private $proxy;
59
60	/**
61	* Tracks whether stamp_html_element() has been called in single-output mode during the current request.
62	*
63	* When wc_order_attribution_allow_multiple_elements filter returns false,
64	* this flag prevents duplicate outputs across multiple action hooks within a single request.
65	*
66	* Note: This flag is reset at the start of each request in on_init() to ensure
67	* proper behavior in persistent PHP environments (PHP-FPM, OpCache).
68	*
69	* @var bool
70	*/
71	private static $is_stamp_html_called = false;
72
73	/**
74	* Initialization method.
75	*
76	* Takes the place of the constructor within WooCommerce Dependency injection.
77	*
78	* @internal
79	*
80	* @param LegacyProxy $proxy The legacy proxy.
81	* @param FeaturesController $controller The feature controller.
82	* @param WPConsentAPI $consent The WPConsentAPI integration.
83	*/
84	final public function init( LegacyProxy $proxy, FeaturesController $controller, WPConsentAPI $consent ) {
85	$this->proxy = $proxy;
86	$this->feature_controller = $controller;
87	$this->consent = $consent;
88	$this->logger = $proxy->call_function( 'wc_get_logger' );
89	$this->set_fields_and_prefix();
90	}
91
92	/**
93	* Register this class instance to the appropriate hooks.
94	*
95	* @return void
96	*/
97	public function register() {
98	// Don't run during install.
99	if ( Constants::get_constant( 'WC_INSTALLING' ) ) {
100	return;
101	}
102
103	add_action( 'init', array( $this, 'on_init' ) );
104	}
105
106	/**
107	* Hook into WordPress on init.
108	*/
109	public function on_init() {
110	// Bail if the feature is not enabled.
111	if ( ! $this->feature_controller->feature_is_enabled( 'order_attribution' ) ) {
112	return;
113	}
114
115	// Reset the static flag at the start of each request to prevent issues in persistent PHP environments.
116	self::$is_stamp_html_called = false;
117
118	// Register WPConsentAPI integration.
119	$this->consent->register();
120
121	add_action(
122	'wp_enqueue_scripts',
123	function () {
124	$this->enqueue_scripts_and_styles();
125	}
126	);
127
128	add_action(
129	'admin_enqueue_scripts',
130	function () {
131	$this->enqueue_admin_scripts_and_styles();
132	}
133	);
134
135	/**
136	* Filter set of actions used to stamp the checkout order attribution HTML container element.
137	*
138	* @since 9.0.0
139	*
140	* @param array $stamp_checkout_html_actions The set of actions used to stamp the checkout order attribution HTML container element.
141	*/
142	$stamp_checkout_html_actions = apply_filters(
143	'wc_order_attribution_stamp_checkout_html_actions',
144	array(
145	'woocommerce_checkout_billing',
146	'woocommerce_after_checkout_billing_form',
147	'woocommerce_checkout_shipping',
148	'woocommerce_after_order_notes',
149	'woocommerce_checkout_after_customer_details',
150	)
151	);
152	foreach ( $stamp_checkout_html_actions as $action ) {
153	add_action( $action, array( $this, 'stamp_html_element' ) );
154	}
155
156	add_action( 'woocommerce_register_form', array( $this, 'stamp_html_element' ) );
157
158	// Update order based on submitted fields.
159	add_action(
160	'woocommerce_checkout_order_created',
161	function ( $order ) {
162
163	// Check if this order already has any attribution data to prevent duplicates attribution data.
164	if ( $this->has_attribution( $order ) ) {
165	return;
166	}
167
168	// Nonce check is handled by WooCommerce before woocommerce_checkout_order_created hook.
169	// phpcs:ignore WordPress.Security.NonceVerification
170	$params = $this->get_unprefixed_field_values( $_POST );
171	/**
172	* Run an action to save order attribution data.
173	*
174	* @since 8.5.0
175	*
176	* @param WC_Order $order The order object.
177	* @param array $params Unprefixed order attribution data.
178	*/
179	do_action( 'woocommerce_order_save_attribution_data', $order, $params );
180	}
181	);
182
183	add_action(
184	'woocommerce_order_save_attribution_data',
185	function ( $order, $data ) {
186	$source_data = $this->get_source_values( $data );
187	$this->send_order_tracks( $source_data, $order );
188	$this->set_order_source_data( $source_data, $order );
189	},
190	10,
191	2
192	);
193
194	add_action(
195	'user_register',
196	function ( $customer_id ) {
197	try {
198	$customer = new WC_Customer( $customer_id );
199	$this->set_customer_source_data( $customer );
200	} catch ( Exception $e ) {
201	$this->log( $e->getMessage(), __METHOD__, WC_Log_Levels::ERROR );
202	}
203	}
204	);
205
206	// Add origin data to the order table.
207	add_action(
208	'admin_init',
209	function () {
210	$this->register_order_origin_column();
211	}
212	);
213
214	add_action(
215	'woocommerce_new_order',
216	function ( $order_id, $order ) {
217	$this->maybe_set_admin_source( $order );
218	},
219	2,
220	10
221	);
222	}
223
224	/**
225	* If the order is created in the admin, set the source type and origin to admin/Web admin.
226	* Only execute this if the order is created in the admin interface (or via ajax in the admin interface).
227	*
228	* @param WC_Order $order The recently created order object.
229	*
230	* @since 8.5.0
231	*/
232	private function maybe_set_admin_source( WC_Order $order ) {
233
234	// For ajax requests, bail if the referer is not an admin page.
235	$http_referer = esc_url_raw( wp_unslash( $_SERVER['HTTP_REFERER'] ?? '' ) );
236	$referer_is_admin = 0 === strpos( $http_referer, get_admin_url() );
237	if ( ! $referer_is_admin && wp_doing_ajax() ) {
238	return;
239	}
240
241	// If not admin interface page, bail.
242	if ( ! is_admin() ) {
243	return;
244	}
245
246	$order->add_meta_data( $this->get_meta_prefixed_field_name( 'source_type' ), 'admin' );
247	$order->save();
248	}
249
250	/**
251	* Get all of the field names.
252	*
253	* @return array
254	*/
255	public function get_field_names(): array {
256	return $this->field_names;
257	}
258
259	/**
260	* Get the prefix for the fields.
261	*
262	* @return string
263	*/
264	public function get_prefix(): string {
265	return $this->field_prefix;
266	}
267
268	/**
269	* Scripts & styles for custom source tracking and cart tracking.
270	*/
271	private function enqueue_scripts_and_styles() {
272	wp_enqueue_script(
273	'sourcebuster-js',
274	plugins_url( "assets/js/sourcebuster/sourcebuster{$this->get_script_suffix()}.js", WC_PLUGIN_FILE ),
275	array(),
276	Constants::get_constant( 'WC_VERSION' ),
277	true
278	);
279
280	wp_enqueue_script(
281	'wc-order-attribution',
282	plugins_url( "assets/js/frontend/order-attribution{$this->get_script_suffix()}.js", WC_PLUGIN_FILE ),
283	// Technically we do depend on 'wp-data', 'wc-blocks-checkout' for blocks checkout,
284	// but as implementing conditional dependency on the server-side would be too complex,
285	// we resolve this condition at the client-side.
286	array( 'sourcebuster-js' ),
287	Constants::get_constant( 'WC_VERSION' ),
288	true
289	);
290
291	/**
292	* Filter the lifetime of the cookie used for source tracking.
293	*
294	* @since 8.5.0
295	*
296	* @param float $lifetime The lifetime of the Sourcebuster cookies in months.
297	*
298	* The default value forces Sourcebuster into making the cookies valid for the current session only.
299	*/
300	$lifetime = (float) apply_filters( 'wc_order_attribution_cookie_lifetime_months', 0.00001 );
301
302	/**
303	* Filter the session length for source tracking.
304	*
305	* @since 8.5.0
306	*
307	* @param int $session_length The session length in minutes.
308	*/
309	$session_length = (int) apply_filters( 'wc_order_attribution_session_length_minutes', 30 );
310
311	/**
312	* Filter to enable base64 encoding for cookie values.
313	*
314	* @since 9.0.0
315	*
316	* @param bool $use_base64_cookies True to enable base64 encoding, default is false.
317	*/
318	$use_base64_cookies = apply_filters( 'wc_order_attribution_use_base64_cookies', false );
319
320	/**
321	* Filter to allow tracking.
322	*
323	* @since 8.5.0
324	*
325	* @param bool $allow_tracking True to allow tracking, false to disable.
326	*/
327	$allow_tracking = wc_bool_to_string( apply_filters( 'wc_order_attribution_allow_tracking', true ) );
328
329	// Create Order Attribution JS namespace with parameters.
330	$namespace = array(
331	'params' => array(
332	'lifetime' => $lifetime,
333	'session' => $session_length,
334	'base64' => $use_base64_cookies,
335	'ajaxurl' => admin_url( 'admin-ajax.php' ),
336	'prefix' => $this->field_prefix,
337	'allowTracking' => 'yes' === $allow_tracking,
338	),
339	'fields' => $this->fields,
340	);
341
342	wp_localize_script( 'wc-order-attribution', 'wc_order_attribution', $namespace );
343	}
344
345	/**
346	* Enqueue the stylesheet for admin pages.
347	*
348	* @return void
349	*/
350	private function enqueue_admin_scripts_and_styles() {
351	$screen = get_current_screen();
352	if ( $screen->id !== $this->get_order_screen_id() ) {
353	return;
354	}
355
356	// phpcs:ignore WordPress.WP.EnqueuedResourceParameters.NotInFooter
357	wp_enqueue_script(
358	'woocommerce-order-attribution-admin-js',
359	plugins_url( "assets/js/admin/order-attribution-admin{$this->get_script_suffix()}.js", WC_PLUGIN_FILE ),
360	array( 'jquery' ),
361	Constants::get_constant( 'WC_VERSION' )
362	);
363	}
364
365	/**
366	* Display the origin column in the orders table.
367	*
368	* @param int $order_id The order ID.
369	*
370	* @return void
371	*/
372	private function display_origin_column( $order_id ): void {
373	try {
374	// Ensure we've got a valid order.
375	$order = $this->get_hpos_order_object( $order_id );
376	$this->output_origin_column( $order );
377	} catch ( Exception $e ) {
378	return;
379	}
380	}
381
382	/**
383	* Output the translated origin label for the Origin column in the orders table.
384	*
385	* Default to "Unknown" if no origin is set.
386	*
387	* @param WC_Order $order The order object.
388	*
389	* @return void
390	*/
391	private function output_origin_column( WC_Order $order ) {
392	$source_type = $order->get_meta( $this->get_meta_prefixed_field_name( 'source_type' ) );
393	$source = $order->get_meta( $this->get_meta_prefixed_field_name( 'utm_source' ) );
394	$origin = $this->get_origin_label( $source_type, $source );
395	echo esc_html( $origin );
396	}
397
398	/**
399	* Handles the `<wc-order-attribution-inputs>` element for checkout forms.
400	*
401	* @since 9.0.0
402	* @deprecated 10.5.0 Use stamp_html_element() instead.
403	*
404	* @return void
405	*/
406	public function stamp_checkout_html_element_once() {
407	wc_deprecated_function( __METHOD__, '10.5.0', 'stamp_html_element' );
408	$this->stamp_html_element();
409	}
410
411	/**
412	* Output `<wc-order-attribution-inputs>` element that contributes the order attribution values to the enclosing form.
413	*
414	* Used for customer register forms and checkout forms.
415	*
416	* Note: By default, this method may output multiple instances of the element when called
417	* multiple times (e.g., during checkout form pre-generation and actual rendering).
418	* The JavaScript layer will remove duplicate elements and ensure only one set of data is submitted.
419	*
420	* @return void
421	*/
422	public function stamp_html_element() {
423	/**
424	* Filter to allow sites to opt back into single-output behavior.
425	*
426	* @since 10.5.0
427	*
428	* @param bool $allow_multiple_elements True to allow multiple elements (new behavior), false for single element (old behavior).
429	*/
430	$allow_multiple = apply_filters( 'wc_order_attribution_allow_multiple_elements', true );
431
432	// If single-output mode is enabled, use the static flag to prevent multiple outputs.
433	if ( ! $allow_multiple && self::$is_stamp_html_called ) {
434	return;
435	}
436
437	printf( '<wc-order-attribution-inputs></wc-order-attribution-inputs>' );
438
439	if ( ! $allow_multiple ) {
440	self::$is_stamp_html_called = true;
441	}
442	}
443
444	/**
445	* Save source data for a Customer object.
446	*
447	* @param WC_Customer $customer The customer object.
448	*
449	* @return void
450	*/
451	private function set_customer_source_data( WC_Customer $customer ) {
452	// Nonce check is handled before user_register hook.
453	// phpcs:ignore WordPress.Security.NonceVerification
454	foreach ( $this->get_source_values( $this->get_unprefixed_field_values( $_POST ) ) as $key => $value ) {
455	$customer->add_meta_data( $this->get_meta_prefixed_field_name( $key ), $value );
456	}
457
458	$customer->save_meta_data();
459	}
460
461	/**
462	* Save source data for an Order object.
463	*
464	* @param array $source_data The source data.
465	* @param WC_Order $order The order object.
466	*
467	* @return void
468	*/
469	private function set_order_source_data( array $source_data, WC_Order $order ) {
470	// If all the values are empty, bail.
471	if ( empty( array_filter( $source_data ) ) ) {
472	return;
473	}
474	foreach ( $source_data as $key => $value ) {
475	$order->add_meta_data( $this->get_meta_prefixed_field_name( $key ), $value );
476	}
477
478	$order->save_meta_data();
479	}
480
481	/**
482	* Log a message as a debug log entry.
483	*
484	* @param string $message The message to log.
485	* @param string $method The method that is logging the message.
486	* @param string $level The log level.
487	*/
488	private function log( string $message, string $method, string $level = WC_Log_Levels::DEBUG ) {
489	/**
490	* Filter to enable debug mode.
491	*
492	* @since 8.5.0
493	*
494	* @param string $enabled 'yes' to enable debug mode, 'no' to disable.
495	*/
496	if ( 'yes' !== apply_filters( 'wc_order_attribution_debug_mode_enabled', 'no' ) ) {
497	return;
498	}
499
500	$this->logger->log(
501	$level,
502	sprintf( '%s %s', $method, $message ),
503	array( 'source' => 'woocommerce-order-attribution' )
504	);
505	}
506
507	/**
508	* Send order source data to Tracks.
509	*
510	* @param array $source_data The source data.
511	* @param WC_Order $order The order object.
512	*
513	* @return void
514	*/
515	private function send_order_tracks( array $source_data, WC_Order $order ) {
516	$origin_label = $this->get_origin_label(
517	$source_data['source_type'] ?? '',
518	$source_data['utm_source'] ?? '',
519	false
520	);
521
522	$tracks_data = array(
523	'order_id' => $order->get_id(),
524	'source_type' => $source_data['source_type'] ?? '',
525	'medium' => $source_data['utm_medium'] ?? '',
526	'source' => $source_data['utm_source'] ?? '',
527	'device_type' => strtolower( $source_data['device_type'] ?? 'unknown' ),
528	'origin_label' => strtolower( $origin_label ),
529	'session_pages' => $source_data['session_pages'] ?? 0,
530	'session_count' => $source_data['session_count'] ?? 0,
531	'order_total' => $order->get_total(),
532	'customer_registered' => $order->get_customer_id() ? 'yes' : 'no',
533	);
534
535	if ( function_exists( 'wc_admin_record_tracks_event' ) ) {
536	wc_admin_record_tracks_event( 'order_attribution', $tracks_data );
537	}
538	}
539
540	/**
541	* Get the screen ID for the orders page.
542	*
543	* @return string
544	*/
545	private function get_order_screen_id(): string {
546	return OrderUtil::custom_orders_table_usage_is_enabled() ? wc_get_page_screen_id( 'shop-order' ) : 'shop_order';
547	}
548
549	/**
550	* Register the origin column in the orders table.
551	*
552	* This accounts for the differences in hooks based on whether HPOS is enabled or not.
553	*
554	* @return void
555	*/
556	private function register_order_origin_column() {
557	$screen_id = $this->get_order_screen_id();
558
559	$add_column = function ( $columns ) {
560	$columns['origin'] = esc_html__( 'Origin', 'woocommerce' );
561
562	return $columns;
563	};
564	// HPOS and non-HPOS use different hooks.
565	add_filter( "manage_{$screen_id}_columns", $add_column );
566	add_filter( "manage_edit-{$screen_id}_columns", $add_column );
567
568	$display_column = function ( $column_name, $order_id ) {
569	if ( 'origin' !== $column_name ) {
570	return;
571	}
572	$this->display_origin_column( $order_id );
573	};
574	// HPOS and non-HPOS use different hooks.
575	add_action( "manage_{$screen_id}_custom_column", $display_column, 10, 2 );
576	add_action( "manage_{$screen_id}_posts_custom_column", $display_column, 10, 2 );
577	}
578
579	/**
580	* Check if this order already has any attribution data
581	*
582	* @param WC_Order $order The order object.
583	*
584	* @return bool
585	* @since 9.8.0
586	*/
587	public function has_attribution( $order ) {
588	foreach ( $this->field_names as $field ) {
589	if ( $order->meta_exists( $this->get_meta_prefixed_field_name( $field ) ) ) {
590	return true;
591	}
592	}
593	return false;
594	}
595	}
596