Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
70.83%
17 / 24
60.00%
6 / 10
 CRAP
0.00%
0 / 1
Sessions_By_Device_Controller
69.57%
16 / 23
60.00%
6 / 10
 12.82
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%
4 / 4
100.00%
1 / 1
 1
 format_row_for_csv
100.00%
5 / 5
100.00%
1 / 1
 1
 get_default_values
100.00%
4 / 4
100.00%
1 / 1
 1
 get_fields
0.00%
0 / 4
0.00%
0 / 1
 2
 get_matching_field
0.00%
0 / 1
0.00%
0 / 1
 2
 get_identifying_fields
0.00%
0 / 1
0.00%
0 / 1
 2
 get_empty_row_check_field
0.00%
0 / 1
0.00%
0 / 1
 2
1<?php
2/**
3 * REST API Reports Sessions by Device 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
12defined( 'ABSPATH' ) || exit;
13
14use Automattic\Jetpack\PremiumAnalytics\Reports\Export\Abstract_Csv_Report_Controller;
15
16/**
17 * Sessions by Device CSV Export Controller.
18 *
19 * Handles CSV exports for the Sessions by Device report.
20 * Note: This is a ranked list report, not a time-series report.
21 * Comparison mode is supported using ID-based merging (matching by device_type).
22 *
23 * @since 0.1.0
24 */
25class Sessions_By_Device_Controller extends Abstract_Csv_Report_Controller {
26
27    /**
28     * Get the report key for this controller.
29     *
30     * @return string The report key.
31     */
32    public function get_report_key(): string {
33        return 'sessionsbydevice';
34    }
35
36    /**
37     * Get the report label for this controller.
38     *
39     * @return string The report label.
40     */
41    public function get_report_label(): string {
42        return __( 'Sessions by Device', 'jetpack-premium-analytics-pkg' );
43    }
44
45    /**
46     * Get the data endpoint for this controller.
47     *
48     * @return string The data endpoint.
49     */
50    public function get_data_endpoint(): string {
51        return 'reports/sessions/by-device';
52    }
53
54    /**
55     * Get the column headers for this controller.
56     *
57     * @param string|null $interval Optional time interval for dynamic headers.
58     * @return array The column headers.
59     */
60    public function get_column_headers( ?string $interval = null ): array { // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable -- Signature required by the report controller interface.
61        return array(
62            'device_type'     => __( 'Device type', 'jetpack-premium-analytics-pkg' ),
63            'active_sessions' => __( 'Sessions', 'jetpack-premium-analytics-pkg' ),
64        );
65    }
66
67    /**
68     * Format a row for CSV export.
69     *
70     * @param array       $item     The row data.
71     * @param string|null $interval Optional time interval for formatting.
72     * @return array The formatted row.
73     */
74    public function format_row_for_csv( array $item, ?string $interval = null ): array { // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable -- Signature required by the report controller interface.
75        $defaults = $this->get_default_values();
76
77        return array(
78            'device_type'     => $item['device_type'] ?? $defaults['device_type'],
79            'active_sessions' => $item['active_sessions'] ?? $defaults['active_sessions'],
80        );
81    }
82
83    /**
84     * Get default values for missing data fields.
85     *
86     * @return array Array of field_name => default_value pairs.
87     */
88    public function get_default_values(): array {
89        return array(
90            'device_type'     => '',
91            'active_sessions' => 0,
92        );
93    }
94
95    /**
96     * Get the list of API fields needed for this report.
97     *
98     * @return array
99     */
100    public function get_fields(): array {
101        return array(
102            'device_type',
103            'active_sessions',
104        );
105    }
106
107    /**
108     * Get the matching field for comparison data alignment.
109     *
110     * Sessions by Device is a ranked report, so comparison data should be matched by device_type.
111     *
112     * @return string|null
113     */
114    public function get_matching_field(): ?string {
115        return 'device_type';
116    }
117
118    /**
119     * Get the identifying fields that should be preserved in comparison data.
120     *
121     * When a device exists in the original period but not in the comparison period,
122     * the device_type should still be shown for clarity.
123     *
124     * @return array Array of field names to preserve.
125     */
126    public function get_identifying_fields(): array {
127        return array( 'device_type' );
128    }
129
130    /**
131     * Get the field name to check for emptiness.
132     *
133     * @return array The field names to check.
134     */
135    public function get_empty_row_check_field() {
136        return array( 'device_type' );
137    }
138}