← All changes | includes/Sync/Order_Write_Payload.php +130 -42 1.10.18 → 1.10.22 View file →

		@@ -15,32 +15,30 @@
15	15	/**
16	16	* Shapes a POS order document into the body forwarded to the STOCK wc/v3 orders
17	17	* controller.
18	18	*
19		- * The v2 write surface owns two halves: the generic write protocol (envelope,
20		- * replay, CAS, checkpoint) and the order-specific payload shaping that makes a
21		- * POS order document survive wc/v3's strict schema and its remove-and-reapply
22		- * line semantics. This class is the second half, extracted verbatim from
23		- * API\V2\Write_Controller so the protocol half stays legible; the shaping rules
24		- * themselves are unchanged. Client-date validation and tax-ID persistence are
25		- * shared with the v1 lane; the remaining shaping rules are not.
	19	+ * V1 = API\V1\Orders_Controller; V2 = API\V2\Writers\Order_Writer.
	20	+ * V1 shapes create_item/update_item through for_create/for_partial_update;
	21	+ * V2 shapes prepare_create/prepare_order_update_after_read through for_create/for_update.
26	22	*
27		- * Lane differences still to be reconciled (V1 = API\V1\Orders_Controller; V2 = API\V2\Writers\Order_Writer):
28		- * - Coupons: V1::calculate_coupons vs reconcile_order_coupon_lines: v1 skips empty codes; v2 forwards malformed lines for rejection; v2 reconciles updates only.
29		- * - Product identity: V1::get_product_id vs normalize_line_item_product_identity: v1 uses loose zero comparison; v2 requires numeric zero and supplies a misc SKU sentinel.
30		- * - Misc SKU: V1::maybe_set_item_meta_data vs normalize_line_item_product_identity: v1 uses isset and the stored product ID; v2 requires posted zero, a string SKU, and trims it.
31		- * - Any attributes: V1::maybe_set_item_meta_data vs recover_any_variation_attributes: v1 uses stored identity and updates by meta ID (default ''); v2 uses posted IDs (product default 0) and appends only missing keys.
32		- * - Variation dedupe: V1::prepare_line_items vs drop_unchanged_variation_line_identity: v1 prunes duplicate rows after preparation; v2 drops unchanged binding IDs before forwarding.
33		- * - Tombstones/omissions: V1 uses WC item deletion; v2 preserves explicit product_id null before identity dedupe and adds deletion markers for omitted items; v1 has no omission pass.
34		- * - Item UUIDs: V1 uses WC posted item IDs; reconcile_order_item_ids restores missing IDs from unique UUID matches on v2.
35		- * - Billing email: V1::wcpos_validate_billing_email/get_item_schema allow empty values; without_empty_billing_email drops ''/null on v2, whose writer explicitly clears '' on update.
36		- * - Display fields: V1::get_item_schema relaxes parent_name; sanitize_order_wc_payload drops null parent_name, image, and display meta fields on v2.
37		- * - Client date: V1 create filter reads raw JSON; V2::prepare_create reads the document; both now use validate_client_created_gmt (absent/null/empty means no override).
38		- * - Tax IDs: v1 coerces, v2 rejects incomplete entries; V1 refreshes its response after persist_tax_ids; V2::persist uses the same snapshot (absent snapshots on create only; [] clears).
39		- * - Audit: V1::wcpos_before_order_object_save/create_item/update_item vs V2 audit phases: v2 also handles reassignment, offline payment assertions, and unpaid provenance updates.
40		- * - Reserved stock: V1::save_object uses request params (absent values null); V2::forward_with_reserved_stock uses payload defaults (status/transaction '', paid false); both use around_paid_create.
41		- * - Write intent: both lanes declare through Services\Order_Write_Intent (v1 at create_item, v2 at Order_Writer::forward); v1 update and direct wc/v3 rely on the ad-hoc intent from the request.
42		- * - HPOS caps: V1 permission overrides retry broad edit/delete order caps; V2 Write_Controller::wcpos_check_permissions remaps read/create and ownership-sensitive edit/delete caps; no payload rule.
	23	+ * Shared through this class (both lanes):
	24	+ * - Product identity and misc SKU: V1 create_item/update_item shaping; V2 create/update shaping.
	25	+ * - "Any" attribute recovery: V1 create_item/update_item shaping; V2 create/update shaping; posted keys win.
	26	+ * - Unchanged identity dedupe: V1 update_item shaping; V2 update shaping skips set_product() for an unchanged binding (#1456 duplicate rows; catalog name/tax_class resets).
	27	+ * - Item-UUID ID reconciliation: V1 update_item shaping; V2 update shaping restores uniquely matched IDs.
	28	+ * - Stored identity for id-only update lines: both update shapes fill product/variation ids from the stored item before the rules above run.
	29	+ * - Display-field and image drops: V1 create_item/update_item shaping; V2 create/update shaping.
	30	+ * - Client date: V1 create_item filter and V2 prepare_create use validate_client_created_gmt.
	31	+ * - Tax-ID persistence: V1 create_item/update_item response refresh and V2 persist use persist_tax_ids.
	32	+ *
	33	+ * Deliberately lane-specific (ruled 2026-09-18):
	34	+ * - Empty coupon code: V1 calculate_coupons skips it so released 1.x clients do not strand orders; V2 forwards for WC's 400.
	35	+ * - Omitted items: V1 retains WC partial-document semantics; V2 adds deletion markers; not all 1.x clients post full documents.
	36	+ * - Incomplete tax IDs: V1 coerces, V2 rejects; parked until Paul's #1724 rework.
	37	+ *
	38	+ * v1's schema relaxations in get_item_schema() are the validation-time half of the
	39	+ * same tolerance this class expresses at the forward seam. V1 updates retain an
	40	+ * explicit empty billing email; V2 drops it here and its writer clears it explicitly.
43	41	*/
44	42	final class Order_Write_Payload {
45	43	/**
46	44	* Shape a CREATE payload for the wc/v3 forward.
		@@ -49,9 +47,9 @@
49	47	*
50	48	* @return array The forwardable payload.
51	49	*/
52	50	public function for_create( array $payload ): array {
53		- return $this->sanitize_order_wc_payload( $payload );
	51	+ return $this->sanitize_order_wc_payload( $this->without_empty_billing_email( $payload ) );
54	52	}
55	53
56	54	/**
57	55	* Shape an UPDATE payload for the wc/v3 forward.
		@@ -71,17 +69,100 @@
71	69	if ( ! $order instanceof \WC_Abstract_Order ) {
72	70	$order = false;
73	71	}
74	72	$payload = $this->reconcile_order_item_ids( $order, $payload );
	73	+ $payload = $this->hydrate_line_identity_from_stored( $order, $payload );
75	74	$payload = $this->remove_omitted_order_items( $order, $payload );
76	75	$payload = $this->reconcile_order_coupon_lines( $order, $payload );
	76	+ $payload = $this->without_empty_billing_email( $payload );
77	77	$payload = $this->sanitize_order_wc_payload( $payload );
78	78	// Runs last: it reads the FORWARDED line shape, after normalize_line_item_product_identity
79	79	// has already resolved the posted sku (which outranks the ids in wc/v3's get_product_id).
80		- return $this->drop_unchanged_variation_line_identity( $order, $payload );
	80	+ return $this->drop_unchanged_line_identity( $order, $payload );
81	81	}
82	82
83	83	/**
	84	+ * Shape the v1 lane's partial update; see for_update for the full-document shape.
	85	+ *
	86	+ * The 2026-09-18 rulings omit omission markers and coupon reconciliation here.
	87	+ * Retain billing.email: '' so WooCommerce applies the deliberate clear directly.
	88	+ *
	89	+ * @param int $order_id Resolved order ID.
	90	+ * @param array $payload Partial update payload.
	91	+ * @return array The forwardable payload.
	92	+ */
	93	+ public function for_partial_update( int $order_id, array $payload ): array {
	94	+ $order = wc_get_order( $order_id );
	95	+ if ( ! $order instanceof \WC_Abstract_Order ) {
	96	+ $order = false;
	97	+ }
	98	+ $payload = $this->reconcile_order_item_ids( $order, $payload );
	99	+ $payload = $this->hydrate_line_identity_from_stored( $order, $payload );
	100	+ $payload = $this->sanitize_order_wc_payload( $payload );
	101	+ // Runs last for the same load-bearing reason as for_update: inspect the forwarded identity.
	102	+ return $this->drop_unchanged_line_identity( $order, $payload );
	103	+ }
	104	+
	105	+ /**
	106	+ * Fill an update line's product identity from the stored item it names.
	107	+ *
	108	+ * A line posted by `id` without `product_id` and/or `variation_id` is a
	109	+ * partial-document edit of a stored line. The identity rules below read the
	110	+ * POSTED identity (the "any" recovery needs BOTH the parent and the variation;
	111	+ * the misc-sku rule needs to tell a misc line from a catalog one), so without it
	112	+ * a display-only attribute choice or a retyped misc sku was silently dropped —
	113	+ * the deleted v1 override read the stored item instead. Each ABSENT key is
	114	+ * filled on its own, but only while every POSTED key still matches the stored
	115	+ * binding: a posted id that differs is a re-bind (say, a variation line moved to
	116	+ * a simple product by posting the new product_id alone), and wc/v3 ranks a
	117	+ * variation id above a product id, so handing that line its old variation_id
	118	+ * would silently keep the old binding. A posted `product_id: null` is wc/v3's
	119	+ * remove-this-line marker, which leaves the whole line alone.
	120	+ * drop_unchanged_line_identity removes the filled identity again when it matches
	121	+ * the stored binding, so an id-only edit forwards id-only, as it always did.
	122	+ *
	123	+ * @param \WC_Abstract_Order|false $order Loaded order, or false when the id does not resolve.
	124	+ * @param array $payload Update payload with ids reconciled.
	125	+ * @return array Payload whose id-only product lines carry their stored identity.
	126	+ */
	127	+ private function hydrate_line_identity_from_stored( $order, array $payload ): array {
	128	+ if ( ! $order || ! isset( $payload['line_items'] ) || ! is_array( $payload['line_items'] ) ) {
	129	+ return $payload;
	130	+ }
	131	+ foreach ( $payload['line_items'] as $i => $line ) {
	132	+ if ( ! is_array( $line ) || empty( $line['id'] ) || ! is_numeric( $line['id'] ) ) {
	133	+ continue;
	134	+ }
	135	+ if ( array_key_exists( 'product_id', $line ) && null === $line['product_id'] ) {
	136	+ continue;
	137	+ }
	138	+ $needs_product = ! array_key_exists( 'product_id', $line );
	139	+ $needs_variation = ! array_key_exists( 'variation_id', $line );
	140	+ if ( ! $needs_product && ! $needs_variation ) {
	141	+ continue;
	142	+ }
	143	+ $item = $order->get_item( (int) $line['id'] );
	144	+ if ( ! $item instanceof WC_Order_Item_Product ) {
	145	+ continue;
	146	+ }
	147	+ // A posted key that differs from the stored binding is a re-bind: forward as posted.
	148	+ if ( ! $needs_product && ( ! is_numeric( $line['product_id'] ) || (int) $line['product_id'] !== $item->get_product_id() ) ) {
	149	+ continue;
	150	+ }
	151	+ if ( ! $needs_variation && ( ! is_numeric( $line['variation_id'] ) || (int) $line['variation_id'] !== $item->get_variation_id() ) ) {
	152	+ continue;
	153	+ }
	154	+ if ( $needs_product ) {
	155	+ $payload['line_items'][ $i ]['product_id'] = $item->get_product_id();
	156	+ }
	157	+ if ( $needs_variation ) {
	158	+ $payload['line_items'][ $i ]['variation_id'] = $item->get_variation_id();
	159	+ }
	160	+ }
	161	+ return $payload;
	162	+ }
	163	+
	164	+ /**
84	165	* Validate the client creation time; bare GMT values are UTC, not store time.
85	166	*
86	167	* @param array $payload Original order document (raw JSON on v1).
87	168	* @return int|null|WP_Error UTC timestamp, null when absent/empty, or a 400 error.
		@@ -140,19 +221,20 @@
140	221	*
141	222	* The v1 surface relaxed the wc/v3 order schema for POS realities (walk-in
142	223	* sales have no email; client line items carry a nullable parent_name that
143	224	* WC recomputes anyway) by editing the POS controller's schema — see
144		- * V1\Orders_Controller::wcpos_get_item_schema(). The v2 write surface
	225	+ * V1\Orders_Controller::get_item_schema(). The v2 write surface
145	226	* forwards to the STOCK wc/v3 controller, whose strict schema turns those
146	227	* POS-legit values into rest_invalid_param 400s (a rejected CREATE then
147	228	* strands the record client-side: every later update 404s). Express the same
148	229	* tolerance by dropping the values WC would reject:
149		- * - billing.email '' / null → dropped (absent means "no email"; '' fails the format check)
150	230	* - line_items[n].parent_name null → dropped (schema wants string; the server recomputes it)
151	231	* - meta_data display fields → dropped (WC derives them and ignores them on write)
152	232	* - line_items[].image → dropped (server-derived display data; acks serialize
153	233	* image.id as '' for imageless products, which wc/v3's integer schema rejects
154	234	* when a client re-pushes its full document)
	235	+ * The billing-email drop is not here: for_create and for_update apply it, the
	236	+ * partial-update shape keeps '' so WooCommerce applies the deliberate clear.
155	237	*
156	238	* @param array $payload Order payload about to be forwarded to wc/v3.
157	239	*
158	240	* @return array The payload with WC-rejected POS values dropped.
		@@ -158,9 +240,8 @@
158	240	* @return array The payload with WC-rejected POS values dropped.
159	241	*/
160	242	private function sanitize_order_wc_payload( array $payload ): array {
161	243	$payload = $this->recover_any_variation_attributes( $payload );
162		- $payload = $this->without_empty_billing_email( $payload );
163	244	if ( isset( $payload['line_items'] ) && is_array( $payload['line_items'] ) ) {
164	245	foreach ( $payload['line_items'] as $i => $line ) {
165	246	if ( is_array( $line ) && array_key_exists( 'parent_name', $line ) && null === $line['parent_name'] ) {
166	247	unset( $payload['line_items'][ $i ]['parent_name'] );
		@@ -404,15 +485,19 @@
404	485	return $payload;
405	486	}
406	487
407	488	/**
408		- * Drop the redundant product identity from update lines whose variation binding
409		- * is unchanged — the v2 port of V1\Orders_Controller::prepare_line_items' dedupe.
	489	+ * Drop the redundant product identity from update lines whose product binding
	490	+ * is unchanged — the port of V1\Orders_Controller::prepare_line_items' dedupe.
410	491	*
411	492	* Stock `WC_REST_Orders_V2_Controller::prepare_line_items` compares products by
412	493	* OBJECT identity (`$product !== $item->get_product()`), which is always true, so
413		- * every posted line re-runs `WC_Order_Item_Product::set_product()`. For a variation
414		- * that calls `set_variation()` → `add_meta_data( 'pa_size', …, true )`, which NULLs
	494	+ * every posted line re-runs `WC_Order_Item_Product::set_product()`. For EVERY
	495	+ * product that copies the catalog's current `name` and `tax_class` onto the stored
	496	+ * item, so an id-only quantity edit of a renamed line would silently reset the
	497	+ * name the merchant sees on the order (posted `name`/`tax_class` are re-applied
	498	+ * afterwards, but an id-only edit posts neither). For a variation it further
	499	+ * calls `set_variation()` → `add_meta_data( 'pa_size', …, true )`, which NULLs
415	500	* the stored attribute row (marking it for deletion) and appends a fresh, id-less
416	501	* copy. `maybe_set_item_meta_data()` then runs `update_meta_data( 'pa_size', …, <id> )`
417	502	* for the posted meta entry, which finds the nulled row BY ID and restores its value —
418	503	* cancelling the delete while the appended copy is still inserted. Net effect: a
		@@ -418,22 +503,25 @@
418	503	* cancelling the delete while the appended copy is still inserted. Net effect: a
419	504	* full-document re-push of an acknowledged variation order grows one duplicate
420	505	* `pa_*` meta row per push (#1456).
421	506	*
422		- * v1 fixed this after the fact by pruning the duplicates. At the v2 forward seam the
	507	+ * v1 previously pruned duplicates after the fact. At the shared payload seam the
423	508	* cause is cheaper to remove: when the posted line already resolves to the SAME
424		- * variation the stored item is bound to, the product binding is a no-op, so drop
425		- * `product_id`/`variation_id` from the forwarded line. `get_product_id()` then returns
426		- * 0 on update, `wc_get_product( 0 )` is false and the whole `set_product()` branch is
427		- * skipped — the stored attribute rows are updated in place, ids and all, so the
428		- * acknowledgement is byte-stable across re-pushes. Lines that genuinely re-bind to a
429		- * different variation still forward their identity and take WC's normal path.
	509	+ * product and variation the stored item is bound to, the product binding is a
	510	+ * no-op, so drop `product_id`/`variation_id` from the forwarded line.
	511	+ * `get_product_id()` then returns 0 on update, `wc_get_product( 0 )` is false and
	512	+ * the whole `set_product()` branch is skipped — the stored name, tax class and
	513	+ * attribute rows are updated in place, ids and all, so the acknowledgement is
	514	+ * byte-stable across re-pushes. Lines that genuinely re-bind to a different
	515	+ * product or variation still forward their identity and take WC's normal path.
	516	+ * A simple line's binding is (product_id, 0); a hydrated id-only line always
	517	+ * carries both keys, so it always qualifies.
430	518	*
431	519	* @param \WC_Abstract_Order|false $order Loaded order, or false when the id does not resolve.
432	520	* @param array $payload Reconciled update payload.
433		- * @return array Payload with no-op variation identity removed from unchanged lines.
	521	+ * @return array Payload with no-op product identity removed from unchanged lines.
434	522	*/
435		- private function drop_unchanged_variation_line_identity( $order, array $payload ): array {
	523	+ private function drop_unchanged_line_identity( $order, array $payload ): array {
436	524	if ( ! isset( $payload['line_items'] ) || ! is_array( $payload['line_items'] ) ) {
437	525	return $payload;
438	526	}
439	527	if ( ! $order ) {
		@@ -443,9 +531,9 @@
443	531	if ( ! is_array( $line ) || empty( $line['id'] ) || ! is_numeric( $line['id'] ) ) {
444	532	continue;
445	533	}
446	534	$item = $order->get_item( (int) $line['id'] );
447		- if ( ! $item instanceof WC_Order_Item_Product || $item->get_variation_id() <= 0 ) {
	535	+ if ( ! $item instanceof WC_Order_Item_Product ) {
448	536	continue;
449	537	}
450	538	// A posted sku wins over the ids in wc/v3's get_product_id(), so a line
451	539	// carrying one is not an unchanged binding as far as WC is concerned.