Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
0.00%
0 / 1
n/a
0 / 0
 CRAP
n/a
0 / 0
1<?php
2/**
3 * CSV Report Controller Interface
4 *
5 * Interface defining the contract for CSV report controllers.
6 * All CSV report controllers must implement this interface to ensure
7 * consistent behavior across the CSV export system.
8 *
9 * @package Automattic\Jetpack\PremiumAnalytics\Reports\Export
10 */
11
12declare( strict_types=1 );
13
14namespace Automattic\Jetpack\PremiumAnalytics\Reports\Export;
15
16defined( 'ABSPATH' ) || exit;
17
18/**
19 * Interface for CSV report controllers.
20 *
21 * @since 0.1.0
22 */
23interface Csv_Report_Controller_Interface extends Registrable_Interface {
24
25    /**
26     * Get the report key (unique identifier).
27     *
28     * @return string The unique report identifier.
29     */
30    public function get_report_key(): string;
31
32    /**
33     * Get the report label (human-readable name).
34     *
35     * @return string The human-readable report name.
36     */
37    public function get_report_label(): string;
38
39    /**
40     * Get the data endpoint (API route).
41     *
42     * @return string The API endpoint for fetching report data.
43     */
44    public function get_data_endpoint(): string;
45
46    /**
47     * Get the column headers for CSV export.
48     *
49     * @param string|null $interval Optional time interval for dynamic headers.
50     * @return array Array of column_key => column_label pairs.
51     */
52    public function get_column_headers( ?string $interval = null ): array;
53
54    /**
55     * Format a single data item for CSV export.
56     *
57     * This method should return the base row data without comparison fields.
58     * Comparison fields are automatically added by format_row_with_comparison().
59     *
60     * @param array       $item     The raw data item.
61     * @param string|null $interval Optional time interval for formatting.
62     * @return array The formatted row for CSV.
63     */
64    public function format_row_for_csv( array $item, ?string $interval = null ): array;
65
66    /**
67     * Get default values for missing data fields.
68     *
69     * This method should return an array of default values for all possible fields
70     * in this report. Used when creating empty items for missing comparison data.
71     *
72     * @return array Array of field_name => default_value pairs.
73     */
74    public function get_default_values(): array;
75
76    /**
77     * Get the batch limit (max items per request).
78     *
79     * @return int The maximum number of items per batch.
80     */
81    public function get_batch_limit(): int;
82
83    /**
84     * Get the matching field for comparison data alignment.
85     *
86     * For ranked reports (top products, sales by coupon), return the field name
87     * to use for matching rows between periods (e.g., 'product_id', 'coupon_code').
88     * For time-series reports, return null to use index-based matching.
89     *
90     * @return string|null The field name for ID-based matching, or null for index-based.
91     */
92    public function get_matching_field(): ?string;
93
94    /**
95     * Get the identifying fields that should be preserved in comparison data.
96     *
97     * For ranked reports with ID-based matching, these fields (like 'product_name',
98     * 'coupon_code') should be copied from the original period to comparison period
99     * when comparison data is missing. This ensures the entity name is always shown
100     * even when there was no activity in the comparison period.
101     *
102     * @return array Array of field names to preserve, or empty array for none.
103     */
104    public function get_identifying_fields(): array;
105
106    /**
107     * Format a row with automatic comparison field handling.
108     *
109     * This method wraps format_row_for_csv() and automatically adds
110     * comparison fields if present in the data.
111     *
112     * @param array       $item     The raw data item.
113     * @param string|null $interval Optional time interval for formatting.
114     * @return array The formatted row with comparison fields.
115     */
116    public function format_row_with_comparison( array $item, ?string $interval = null ): array;
117
118    /**
119     * Whether to use array format for filter values in IN filters.
120     *
121     * When true, filters are built as: filters[0][value][]=id1&filters[0][value][]=id2
122     * When false (default), filters are built as: filters[0][value]=id1,id2 (more URL-efficient)
123     *
124     * Order-attribution endpoints require array format, while most other endpoints
125     * accept comma-separated values which are more URL-efficient.
126     *
127     * @return bool True to use array format, false for comma-separated (default).
128     */
129    public function use_array_filter_format(): bool;
130
131    /**
132     * Whether to include rows with empty identifying fields in the export.
133     *
134     * When true, rows with empty identifying fields will be included in the export
135     * with a custom label. When false (default), they will be skipped.
136     *
137     * This is used by Report_Data_Fetcher when building ID filters for comparison data
138     * to ensure comparison data is fetched for empty rows when needed.
139     *
140     * @return bool True to include empty rows with custom label, false to skip them.
141     */
142    public function should_include_empty_rows(): bool;
143
144    /**
145     * Get the list of fields to request from the API.
146     *
147     * Return only the fields needed for this report to reduce API response
148     * payload size. Return an empty array to request all fields (default).
149     *
150     * @return array Field names to request, or empty array for all fields.
151     */
152    public function get_fields(): array;
153
154    /**
155     * Get additional request parameters for data fetching.
156     *
157     * Controller-specific query parameters merged into every data request
158     * (e.g. date_type, orderby, order, limit).
159     *
160     * @return array Additional parameters to include in data requests.
161     */
162    public function get_additional_params(): array;
163}