woo-postnl / src / Rest_API / V4 / Label / Response_Mapper.php

Response_Mapper.php in PostNL for WooCommerce 5.9.12, at src/Rest_API/V4/Label/Response_Mapper.php

177 lines 5.7 KB

Raw Download Zip

1	<?php
2	/**
3	* Class Rest_API\V4\Label\Response_Mapper file.
4	*
5	* @package PostNLWooCommerce\Rest_API\V4\Label
6	*/
7
8	declare( strict_types = 1 );
9
10	namespace PostNLWooCommerce\Rest_API\V4\Label;
11
12	use Postnl\Sdk\ResponseData\V4\Label;
13	use Postnl\Sdk\ResponseData\V4\ShipmentShippingItem;
14	use Postnl\Sdk\Service\ShipmentDelivery\V4\Response\LabelConfirmResponseInterface;
15
16	if ( ! defined( 'ABSPATH' ) ) {
17	exit;
18	}
19
20	/**
21	* Class Response_Mapper
22	*
23	* Pure reader for the labelconfirm response. Extracts the auto-issued barcode
24	* and the label document(s) without any WooCommerce or filesystem access, so
25	* barcode capture can be asserted in isolation. File writing and merging stay
26	* in the WooCommerce-bound service.
27	*
28	* @since 6.0.0
29	* @package PostNLWooCommerce\Rest_API\V4\Label
30	*/
31	class Response_Mapper {
32
33	/**
34	* Return the first shipment item from the response, or null when empty.
35	*
36	* A single domestic parcel yields exactly one shipment item.
37	*
38	* @param LabelConfirmResponseInterface $response Response from labelconfirm.
39	* @return ShipmentShippingItem\|null
40	*/
41	public static function first_shipment_item( LabelConfirmResponseInterface $response ): ?ShipmentShippingItem {
42	$items = $response->items();
43
44	return $items->isEmpty() ? null : $items->first();
45	}
46
47	/**
48	* Return every shipment item from the response, in order.
49	*
50	* A multi-collo shipment yields one item per collo, each with its own barcode
51	* and label document(s).
52	*
53	* @param LabelConfirmResponseInterface $response Response from labelconfirm.
54	* @return ShipmentShippingItem[]
55	*/
56	public static function all_shipment_items( LabelConfirmResponseInterface $response ): array {
57	return array_values( $response->items()->all() );
58	}
59
60	/**
61	* Return the barcode issued for a shipment item.
62	*
63	* The labelconfirm endpoint auto-issues the barcode and echoes it back on
64	* the item; the fallback is used only when the response omits it (e.g. a
65	* barcode was pre-supplied on the request).
66	*
67	* @param ShipmentShippingItem $item Shipment item from the response.
68	* @param string $fallback Barcode to use when none is returned.
69	* @return string
70	*/
71	public static function get_barcode( ShipmentShippingItem $item, string $fallback = '' ): string {
72	if ( null !== $item->barcode && '' !== $item->barcode ) {
73	return $item->barcode;
74	}
75
76	return $fallback;
77	}
78
79	/**
80	* Return the international partner barcode issued for a shipment item.
81	*
82	* For EU/ROW shipments the labelconfirm response echoes the delivering
83	* partner's barcode and id; both are empty for a domestic shipment.
84	*
85	* @param ShipmentShippingItem $item Shipment item from the response.
86	* @return string
87	*/
88	public static function get_partner_barcode( ShipmentShippingItem $item ): string {
89	// phpcs:ignore WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase -- Third-party SDK DTO property.
90	return null !== $item->partnerBarcode ? $item->partnerBarcode : '';
91	}
92
93	/**
94	* Return the international partner id issued for a shipment item.
95	*
96	* @param ShipmentShippingItem $item Shipment item from the response.
97	* @return string
98	*/
99	public static function get_partner_id( ShipmentShippingItem $item ): string {
100	// phpcs:ignore WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase -- Third-party SDK DTO property.
101	return null !== $item->partnerId ? $item->partnerId : '';
102	}
103
104	/**
105	* Return the non-empty Label objects attached to a shipment item.
106	*
107	* @param ShipmentShippingItem $item Shipment item from the response.
108	* @return Label[]
109	*/
110	public static function get_labels( ShipmentShippingItem $item ): array {
111	if ( null === $item->labels ) {
112	return array();
113	}
114
115	return array_values(
116	array_filter(
117	$item->labels->all(),
118	static function ( Label $label ): bool {
119	return ! $label->isEmpty();
120	}
121	)
122	);
123	}
124
125	/**
126	* Decode a label's base64 document content.
127	*
128	* @param Label $label Label object from the response.
129	* @return string Raw (decoded) label bytes, or empty string when absent.
130	*/
131	public static function decode_content( Label $label ): string {
132	if ( null === $label->label \|\| '' === $label->label ) {
133	return '';
134	}
135
136	// phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_decode -- Decoding a PostNL label document returned base64-encoded by the SDK.
137	$decoded = base64_decode( $label->label, true );
138
139	return false === $decoded ? '' : $decoded;
140	}
141
142	/**
143	* Build a normalized label record matching the shape stored in
144	* _postnl_order_metadata['labels'] by the legacy path, tagged as V4.
145	*
146	* The partner barcode/id are added only for international shipments, where the
147	* labelconfirm response returns them; they are omitted for domestic labels.
148	*
149	* @param string $type Label type slug, e.g. 'label'.
150	* @param string $barcode Barcode for this label.
151	* @param string $filepath Absolute path to the written label file.
152	* @param string $partner_barcode Optional international partner barcode.
153	* @param string $partner_id Optional international partner id.
154	* @return array<string,mixed>
155	*/
156	public static function to_label_record( string $type, string $barcode, string $filepath, string $partner_barcode = '', string $partner_id = '' ): array {
157	$record = array(
158	'type' => $type,
159	'barcode' => $barcode,
160	// phpcs:ignore WordPress.DateTime.CurrentTimeTimestamp.Requested -- Mirrors the legacy label record's created_at timestamp stored in order meta.
161	'created_at' => current_time( 'timestamp' ),
162	'filepath' => $filepath,
163	'api_version' => 'v4',
164	);
165
166	if ( '' !== $partner_barcode ) {
167	$record['partner_barcode'] = $partner_barcode;
168	}
169
170	if ( '' !== $partner_id ) {
171	$record['partner_id'] = $partner_id;
172	}
173
174	return $record;
175	}
176	}
177