class-wc-rest-report-sales-controller.php — WooCommerce 11.0.1

woocommerce / includes / rest-api / Controllers / Version3 / class-wc-rest-report-sales-controller.php

woocommerce / includes / rest-api / Controllers / Version3 Last commit date

class-wc-rest-report-sales-controller.php

155 lines

1	<?php
2	/**
3	* REST API Reports controller
4	*
5	* Handles requests to the reports/sales endpoint.
6	*
7	* @package WooCommerce\RestApi
8	* @since 2.6.0
9	*/
10
11	defined( 'ABSPATH' ) \|\| exit;
12
13	/**
14	* REST API Report Sales controller class.
15	*
16	* @package WooCommerce\RestApi
17	* @extends WC_REST_Report_Sales_V2_Controller
18	*/
19	class WC_REST_Report_Sales_Controller extends WC_REST_Report_Sales_V2_Controller {
20
21	/**
22	* Endpoint namespace.
23	*
24	* @var string
25	*/
26	protected $namespace = 'wc/v3';
27
28	/**
29	* Prepare a report sales object for serialization.
30	*
31	* Extends the v2 response with a per-period `refunds` field inside each
32	* `totals[date]` bucket so consumers can compute net sales per period
33	* without a second request. Top-level `total_refunds` and per-period
34	* `sales` semantics are unchanged.
35	*
36	* @param null $_ Unused.
37	* @param WP_REST_Request<array<string, mixed>> $request Request object.
38	* @return WP_REST_Response
39	*/
40	public function prepare_item_for_response( $_, $request ) {
41	$response = parent::prepare_item_for_response( $_, $request );
42	$data = $response->get_data();
43
44	if ( ! isset( $data['totals'] ) \|\| ! is_array( $data['totals'] ) ) {
45	return $response;
46	}
47
48	// Initialise the refunds bucket on every period so consumers get a
49	// stable shape (decimal string) even on periods with no refunds.
50	foreach ( $data['totals'] as $time => $bucket ) {
51	$data['totals'][ $time ]['refunds'] = wc_format_decimal( 0.00, 2 );
52	}
53
54	// `$this->report` is a WC_Report_Sales_By_Date (the v1 base annotates
55	// it as the abstract WC_Admin_Report). Annotate locally so the call to
56	// the concrete `get_report_data()` typechecks.
57	/** @var WC_Report_Sales_By_Date $report */ // phpcs:ignore Generic.Commenting.DocComment.MissingShort
58	$report = $this->report;
59	$report_data = $report->get_report_data();
60	if ( ! empty( $report_data->refund_lines ) ) {
61	foreach ( $report_data->refund_lines as $refund ) {
62	// Match the bucket key format used by the parent's sales /
63	// orders / items / coupons loops (local time, not UTC) so
64	// refunds line up with their corresponding sales row.
65	// phpcs:ignore WordPress.DateTime.RestrictedFunctions.date_date -- Match adjacent loops in v1 base controller.
66	$time = ( 'day' === $this->report->chart_groupby ) ? date( 'Y-m-d', strtotime( $refund->post_date ) ) : date( 'Y-m', strtotime( $refund->post_date ) );
67
68	if ( ! isset( $data['totals'][ $time ] ) ) {
69	continue;
70	}
71
72	$data['totals'][ $time ]['refunds'] = wc_format_decimal( (float) $data['totals'][ $time ]['refunds'] + (float) $refund->total_refund, 2 );
73	}
74	}
75
76	$response->set_data( $data );
77	return $response;
78	}
79
80	/**
81	* Get the Report's schema, conforming to JSON Schema.
82	*
83	* Extends the v2 schema with the per-period `refunds` field and replaces
84	* the previously incorrect `totals` typing (`array` of `array`) with the
85	* actual object-of-objects shape so the schema reflects reality.
86	*
87	* @return array
88	*/
89	public function get_item_schema() {
90	$schema = parent::get_item_schema();
91
92	$schema['properties']['totals'] = array(
93	'description' => __( 'Totals.', 'woocommerce' ),
94	'type' => 'object',
95	'context' => array( 'view' ),
96	'readonly' => true,
97	'additionalProperties' => array(
98	'type' => 'object',
99	'properties' => array(
100	'sales' => array(
101	'description' => __( 'Gross sales in the period.', 'woocommerce' ),
102	'type' => 'string',
103	'context' => array( 'view' ),
104	'readonly' => true,
105	),
106	'orders' => array(
107	'description' => __( 'Number of orders in the period.', 'woocommerce' ),
108	'type' => 'integer',
109	'context' => array( 'view' ),
110	'readonly' => true,
111	),
112	'items' => array(
113	'description' => __( 'Number of items sold in the period.', 'woocommerce' ),
114	'type' => 'integer',
115	'context' => array( 'view' ),
116	'readonly' => true,
117	),
118	'tax' => array(
119	'description' => __( 'Tax charged in the period.', 'woocommerce' ),
120	'type' => 'string',
121	'context' => array( 'view' ),
122	'readonly' => true,
123	),
124	'shipping' => array(
125	'description' => __( 'Shipping charged in the period.', 'woocommerce' ),
126	'type' => 'string',
127	'context' => array( 'view' ),
128	'readonly' => true,
129	),
130	'discount' => array(
131	'description' => __( 'Discounts applied in the period.', 'woocommerce' ),
132	'type' => 'string',
133	'context' => array( 'view' ),
134	'readonly' => true,
135	),
136	'refunds' => array(
137	'description' => __( 'Refunds issued in the period.', 'woocommerce' ),
138	'type' => 'string',
139	'context' => array( 'view' ),
140	'readonly' => true,
141	),
142	'customers' => array(
143	'description' => __( 'New customers in the period.', 'woocommerce' ),
144	'type' => 'integer',
145	'context' => array( 'view' ),
146	'readonly' => true,
147	),
148	),
149	),
150	);
151
152	return $this->add_additional_fields_schema( $schema );
153	}
154	}
155