Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
74.00%
37 / 50
75.00%
6 / 8
 CRAP
0.00%
0 / 1
Coupon_Use_Over_Time_Controller
73.47%
36 / 49
75.00%
6 / 8
 9.20
0.00%
0 / 1
 get_report_key
100.00%
1 / 1
100.00%
1 / 1
 1
 get_report_label
100.00%
1 / 1
100.00%
1 / 1
 1
 get_data_endpoint
100.00%
1 / 1
100.00%
1 / 1
 1
 get_column_headers
100.00%
11 / 11
100.00%
1 / 1
 1
 get_default_values
100.00%
10 / 10
100.00%
1 / 1
 1
 get_fields
0.00%
0 / 10
0.00%
0 / 1
 2
 format_row_for_csv
100.00%
12 / 12
100.00%
1 / 1
 1
 get_additional_params
0.00%
0 / 3
0.00%
0 / 1
 2
1<?php
2/**
3 * REST API Reports Coupon Use Over Time controller class.
4 *
5 * @package Automattic\Jetpack\PremiumAnalytics\Reports\Export\Exports
6 */
7
8declare( strict_types=1 );
9
10namespace Automattic\Jetpack\PremiumAnalytics\Reports\Export\Exports;
11
12use Automattic\Jetpack\PremiumAnalytics\Reports\Export\Abstract_Csv_Report_Controller;
13
14defined( 'ABSPATH' ) || exit;
15
16/**
17 * Coupon Use Over Time CSV Export Controller.
18 *
19 * Handles CSV exports for the Coupon Use Over Time report, supporting both
20 * single interval and comparison interval data.
21 *
22 * @since $$next-version$$
23 */
24class Coupon_Use_Over_Time_Controller extends Abstract_Csv_Report_Controller {
25
26    /**
27     * Get the report key for this controller.
28     *
29     * @return string The report key.
30     */
31    public function get_report_key(): string {
32        return 'couponuseovertime';
33    }
34
35    /**
36     * Get the report label for this controller.
37     *
38     * @return string The report label.
39     */
40    public function get_report_label(): string {
41        return __( 'Coupon Use Over Time', 'jetpack-premium-analytics' );
42    }
43
44    /**
45     * Get the data endpoint for this controller.
46     *
47     * @return string The data endpoint.
48     */
49    public function get_data_endpoint(): string {
50        return 'reports/coupons/by-date';
51    }
52
53    /**
54     * Get the column headers for this controller.
55     *
56     * @param string|null $interval Optional time interval for dynamic headers.
57     * @return array The column headers.
58     */
59    public function get_column_headers( ?string $interval = null ): array {
60        return array(
61            'time_interval'              => $this->get_interval_label( $interval ),
62            'orders_no'                  => __( 'Total Orders', 'jetpack-premium-analytics' ),
63            'orders_with_coupon'         => __( 'Orders with coupon', 'jetpack-premium-analytics' ),
64            'total_sales'                => __( 'Total sales', 'jetpack-premium-analytics' ),
65            'gross_sales_with_coupon'    => __( 'Gross sales with coupon', 'jetpack-premium-analytics' ),
66            'gross_sales_without_coupon' => __( 'Gross sales without coupon', 'jetpack-premium-analytics' ),
67            'coupons'                    => __( 'Discount amount - Total', 'jetpack-premium-analytics' ),
68            'orders_value_net'           => __( 'Net sales - after discounts', 'jetpack-premium-analytics' ),
69            'coupon_use_pct_of_sales'    => __( 'Coupon use as % of sales', 'jetpack-premium-analytics' ),
70        );
71    }
72
73    /**
74     * Get default values for missing data fields.
75     *
76     * @return array Array of field_name => default_value pairs.
77     */
78    public function get_default_values(): array {
79        return array(
80            'total_orders'             => 0,
81            'orders_with_coupon'       => 0,
82            'total_sales'              => 0,
83            'sales_with_coupon'        => 0,
84            'sales_without_coupon'     => 0,
85            'total_discount_amount'    => 0,
86            'net_sales_after_discount' => 0,
87            'coupon_usage_percentage'  => 0,
88        );
89    }
90
91    /**
92     * Get the list of API fields needed for this report.
93     *
94     * @return array
95     */
96    public function get_fields(): array {
97        // time_interval, date_start, and date_end are always returned by the
98        // API for time-series endpoints and do not need to be requested.
99        return array(
100            'total_orders',
101            'orders_with_coupon',
102            'total_sales',
103            'sales_with_coupon',
104            'sales_without_coupon',
105            'total_discount_amount',
106            'net_sales_after_discount',
107            'coupon_usage_percentage',
108        );
109    }
110
111    /**
112     * Format a row for CSV export.
113     *
114     * @param array       $item     The row data.
115     * @param string|null $interval Optional time interval for formatting.
116     * @return array The formatted row.
117     */
118    public function format_row_for_csv( array $item, ?string $interval = null ): array {
119        $defaults = $this->get_default_values();
120
121        return array(
122            'time_interval'              => $this->format_time_interval( $item, $interval ),
123            'orders_no'                  => (int) ( $item['total_orders'] ?? $defaults['total_orders'] ),
124            'orders_with_coupon'         => (int) ( $item['orders_with_coupon'] ?? $defaults['orders_with_coupon'] ),
125            'total_sales'                => self::format_amount( $item['total_sales'] ?? $defaults['total_sales'] ),
126            'gross_sales_with_coupon'    => self::format_amount( $item['sales_with_coupon'] ?? $defaults['sales_with_coupon'] ),
127            'gross_sales_without_coupon' => self::format_amount( $item['sales_without_coupon'] ?? $defaults['sales_without_coupon'] ),
128            'coupons'                    => self::format_amount( $item['total_discount_amount'] ?? $defaults['total_discount_amount'] ),
129            'orders_value_net'           => self::format_amount( $item['net_sales_after_discount'] ?? $defaults['net_sales_after_discount'] ),
130            'coupon_use_pct_of_sales'    => number_format( (float) ( $item['coupon_usage_percentage'] ?? $defaults['coupon_usage_percentage'] ), 2, '.', '' ) . '%',
131        );
132    }
133
134    /**
135     * Get additional request parameters for data fetching.
136     *
137     * @return array Additional parameters to include in data requests.
138     */
139    public function get_additional_params(): array {
140        return array(
141            'date_type' => self::DEFAULT_DATE_TYPE,
142        );
143    }
144}