OrdersVersionStringInvalidator.php — WooCommerce 10.9.3

woocommerce / src / Internal / Caches / OrdersVersionStringInvalidator.php

woocommerce / src / Internal / Caches Last commit date

OrdersVersionStringInvalidator.php 4 months ago ProductCache.php 5 months ago ProductCacheController.php 5 months ago ProductVersionStringInvalidator.php 4 months ago TaxRateVersionStringInvalidator.php 4 months ago VersionStringGenerator.php 4 months ago

OrdersVersionStringInvalidator.php

347 lines

1	<?php
2
3	declare( strict_types=1 );
4
5	namespace Automattic\WooCommerce\Internal\Caches;
6
7	/**
8	* Order version string invalidation handler.
9	*
10	* This class provides an 'invalidate' method that will invalidate
11	* the version string for a given order, which in turn invalidates
12	* any cached REST API responses containing that order.
13	*/
14	class OrdersVersionStringInvalidator {
15
16	/**
17	* Stores the customer ID of orders before they are saved.
18	* Used to detect customer changes that require list invalidation.
19	*
20	* @var array<int, int> Order ID => Customer ID
21	*/
22	private array $pre_save_customer_ids = array();
23
24	/**
25	* Initialize the invalidator and register hooks.
26	*
27	* Hooks are only registered when both conditions are met:
28	* - The REST API caching feature is enabled
29	* - The backend caching setting is active
30	*
31	* @return void
32	*
33	* @since 10.6.0
34	*
35	* @internal
36	*/
37	final public function init(): void {
38	// We can't use FeaturesController::feature_is_enabled at this point
39	// (before the 'init' action is triggered) because that would cause
40	// "Translation loading for the woocommerce domain was triggered too early" warnings.
41	if ( 'yes' !== get_option( 'woocommerce_feature_rest_api_caching_enabled' ) ) {
42	return;
43	}
44
45	if ( 'yes' === get_option( 'woocommerce_rest_api_enable_backend_caching', 'no' ) ) {
46	$this->register_hooks();
47	}
48	}
49
50	/**
51	* Register all order-related hooks.
52	*
53	* Only WooCommerce hooks are registered (not WordPress post hooks) since these always fire
54	* when an order is created/updated/deleted via the WooCommerce APIs, regardless of HPOS
55	* being active or not.
56	*
57	* @return void
58	*/
59	private function register_hooks(): void {
60	// Hook to capture customer ID before save for change detection.
61	add_action( 'woocommerce_before_order_object_save', array( $this, 'handle_before_order_save' ), 10, 1 );
62
63	// WooCommerce CRUD hooks for orders.
64	add_action( 'woocommerce_new_order', array( $this, 'handle_woocommerce_new_order' ), 10, 2 );
65	add_action( 'woocommerce_update_order', array( $this, 'handle_woocommerce_update_order' ), 10, 2 );
66	add_action( 'woocommerce_before_delete_order', array( $this, 'handle_woocommerce_before_delete_order' ), 10, 2 );
67	add_action( 'woocommerce_trash_order', array( $this, 'handle_woocommerce_trash_order' ), 10, 1 );
68	add_action( 'woocommerce_untrash_order', array( $this, 'handle_woocommerce_untrash_order' ), 10, 2 );
69
70	// Status change hook.
71	add_action( 'woocommerce_order_status_changed', array( $this, 'handle_woocommerce_order_status_changed' ), 10, 4 );
72
73	// Refund hooks.
74	add_action( 'woocommerce_order_refunded', array( $this, 'handle_woocommerce_order_refunded' ), 10, 2 );
75	add_action( 'woocommerce_refund_deleted', array( $this, 'handle_woocommerce_refund_deleted' ), 10, 2 );
76	}
77
78	// phpcs:disable Generic.CodeAnalysis.UnusedFunctionParameter.FoundAfterLastUsed
79
80	/**
81	* Handle the woocommerce_before_order_object_save hook.
82	*
83	* Captures the customer ID before save to detect changes.
84	*
85	* @param \WC_Order $order The order being saved.
86	*
87	* @return void
88	*
89	* @since 10.6.0
90	*
91	* @internal
92	*/
93	public function handle_before_order_save( $order ): void {
94	if ( ! $order instanceof \WC_Order \|\| 'shop_order' !== $order->get_type() ) {
95	return;
96	}
97
98	$order_id = $order->get_id();
99	if ( $order_id > 0 ) {
100	$this->pre_save_customer_ids[ $order_id ] = (int) $order->get_data()['customer_id'];
101	}
102	}
103
104	/**
105	* Handle the woocommerce_new_order hook.
106	*
107	* @param int $order_id The order ID.
108	* @param \WC_Order $order The order object.
109	*
110	* @return void
111	*
112	* @since 10.6.0
113	*
114	* @internal
115	*/
116	public function handle_woocommerce_new_order( $order_id, $order ): void {
117	$this->invalidate( (int) $order_id );
118	$this->invalidate_orders_list();
119	}
120
121	/**
122	* Handle the woocommerce_update_order hook.
123	*
124	* @param int $order_id The order ID.
125	* @param \WC_Order $order The order object.
126	*
127	* @return void
128	*
129	* @since 10.6.0
130	*
131	* @internal
132	*/
133	public function handle_woocommerce_update_order( $order_id, $order ): void {
134	$order_id = (int) $order_id;
135	$this->invalidate( $order_id );
136
137	if ( $this->did_customer_change( $order_id, $order ) ) {
138	$this->invalidate_orders_list();
139	}
140
141	unset( $this->pre_save_customer_ids[ $order_id ] );
142	}
143
144	/**
145	* Check if the customer ID changed during the update.
146	*
147	* @param int $order_id The order ID.
148	* @param \WC_Order $order The order object (after save).
149	*
150	* @return bool True if customer changed.
151	*/
152	private function did_customer_change( int $order_id, $order ): bool {
153	if ( ! isset( $this->pre_save_customer_ids[ $order_id ] ) ) {
154	return false;
155	}
156
157	$old_customer_id = $this->pre_save_customer_ids[ $order_id ];
158	$new_customer_id = $order instanceof \WC_Order ? (int) $order->get_customer_id() : 0;
159
160	return $old_customer_id !== $new_customer_id;
161	}
162
163	/**
164	* Handle the woocommerce_before_delete_order hook.
165	*
166	* @param int $order_id The order ID.
167	* @param \WC_Order $order The order object.
168	*
169	* @return void
170	*
171	* @since 10.6.0
172	*
173	* @internal
174	*/
175	public function handle_woocommerce_before_delete_order( $order_id, $order ): void {
176	$this->invalidate( (int) $order_id );
177	$this->invalidate_orders_list();
178	}
179
180	/**
181	* Handle the woocommerce_trash_order hook.
182	*
183	* @param int $order_id The order ID.
184	*
185	* @return void
186	*
187	* @since 10.6.0
188	*
189	* @internal
190	*/
191	public function handle_woocommerce_trash_order( $order_id ): void {
192	$this->invalidate( (int) $order_id );
193	$this->invalidate_orders_list();
194	}
195
196	/**
197	* Handle the woocommerce_untrash_order hook.
198	*
199	* @param int $order_id The order ID.
200	* @param string $previous_status The previous order status before trashing.
201	*
202	* @return void
203	*
204	* @since 10.6.0
205	*
206	* @internal
207	*/
208	public function handle_woocommerce_untrash_order( $order_id, $previous_status ): void {
209	$this->invalidate( (int) $order_id );
210	$this->invalidate_orders_list();
211	}
212
213	/**
214	* Handle the woocommerce_order_status_changed hook.
215	*
216	* Status changes affect which orders appear in status-filtered collection endpoints,
217	* so we always invalidate the orders list.
218	*
219	* @param int $order_id The order ID.
220	* @param string $from_status The old status.
221	* @param string $to_status The new status.
222	* @param \WC_Order $order The order object.
223	*
224	* @return void
225	*
226	* @since 10.6.0
227	*
228	* @internal
229	*/
230	public function handle_woocommerce_order_status_changed( $order_id, $from_status, $to_status, $order ): void {
231	$this->invalidate( (int) $order_id );
232	$this->invalidate_orders_list();
233	}
234
235	/**
236	* Handle the woocommerce_order_refunded hook.
237	*
238	* @param int $order_id The parent order ID.
239	* @param int $refund_id The refund ID.
240	*
241	* @return void
242	*
243	* @since 10.6.0
244	*
245	* @internal
246	*/
247	public function handle_woocommerce_order_refunded( $order_id, $refund_id ): void {
248	$order_id = (int) $order_id;
249	$refund_id = (int) $refund_id;
250
251	$this->invalidate( $order_id );
252	$this->invalidate_refund( $refund_id );
253	$this->invalidate_order_refunds_list( $order_id );
254	$this->invalidate_refunds_list();
255	}
256
257	/**
258	* Handle the woocommerce_refund_deleted hook.
259	*
260	* @param int $refund_id The refund ID.
261	* @param int $order_id The parent order ID.
262	*
263	* @return void
264	*
265	* @since 10.6.0
266	*
267	* @internal
268	*/
269	public function handle_woocommerce_refund_deleted( $refund_id, $order_id ): void {
270	$order_id = (int) $order_id;
271	$refund_id = (int) $refund_id;
272
273	$this->invalidate( $order_id );
274	$this->invalidate_refund( $refund_id );
275	$this->invalidate_order_refunds_list( $order_id );
276	$this->invalidate_refunds_list();
277	}
278
279	// phpcs:enable Generic.CodeAnalysis.UnusedFunctionParameter.FoundAfterLastUsed
280
281	/**
282	* Invalidate an order version string.
283	*
284	* @param int $order_id The order ID.
285	*
286	* @return void
287	*
288	* @since 10.6.0
289	*/
290	public function invalidate( int $order_id ): void {
291	wc_get_container()->get( VersionStringGenerator::class )->delete_version( "order_{$order_id}" );
292	}
293
294	/**
295	* Invalidate a refund version string.
296	*
297	* @param int $refund_id The refund ID.
298	*
299	* @return void
300	*
301	* @since 10.6.0
302	*/
303	public function invalidate_refund( int $refund_id ): void {
304	wc_get_container()->get( VersionStringGenerator::class )->delete_version( "refund_{$refund_id}" );
305	}
306
307	/**
308	* Invalidate the orders list version string.
309	*
310	* This should be called when orders are created, deleted, change status,
311	* or change customer, as these operations affect collection/list endpoints.
312	*
313	* @return void
314	*/
315	private function invalidate_orders_list(): void {
316	wc_get_container()->get( VersionStringGenerator::class )->delete_version( 'list_orders' );
317	}
318
319	/**
320	* Invalidate the refunds list version string.
321	*
322	* This should be called when refunds are created or deleted,
323	* as these operations affect the /refunds collection endpoint.
324	*
325	* @return void
326	*/
327	private function invalidate_refunds_list(): void {
328	wc_get_container()->get( VersionStringGenerator::class )->delete_version( 'list_refunds' );
329	}
330
331	/**
332	* Invalidate the refunds list version string for a specific order.
333	*
334	* This should be called when refunds are created or deleted for an order,
335	* as these operations affect the /orders/{id}/refunds collection endpoint.
336	*
337	* @param int $order_id The parent order ID.
338	*
339	* @return void
340	*/
341	private function invalidate_order_refunds_list( int $order_id ): void {
342	if ( $order_id > 0 ) {
343	wc_get_container()->get( VersionStringGenerator::class )->delete_version( "list_order_refunds_{$order_id}" );
344	}
345	}
346	}
347