metricool / app / Support / Builders / StatsTimelineBuilder.php

StatsTimelineBuilder.php in Metricool – Social media and site statistics 2.1.1, at app/Support/Builders/StatsTimelineBuilder.php

151 lines 4.0 KB

Raw Download Zip

1	<?php
2
3	declare(strict_types=1);
4
5	namespace Metricool\Support\Builders;
6
7	use Metricool\Vendor\Carbon\Carbon;
8	use Metricool\Support\Helpers\Collection;
9	use Metricool\Http\Metricool\DTOs\TimelineDTO;
10	use Metricool\Http\Metricool\Entities\TimelineStatistics;
11
12	/**
13	* Builds a timeline from a collection of metrics and their corresponding statistics.
14	* @see AnalyticsService for usage example
15	*/
16	class StatsTimelineBuilder
17	{
18	/**
19	* @var array $timeline This holds all the results of the timeline
20	*/
21	protected array $timeline = [];
22
23	/**
24	* Metrics holds the name of the Metric, the label and results of the API request
25	* @var array<string, array{
26	* name: string,
27	* label: string,
28	* statistics?: TimelineStatistics,
29	* results?: Collection\|TimelineDTO[],
30	* useInTimeline: bool,
31	* }>
32	**/
33	protected array $metrics = [];
34
35	/**
36	* @var string $isoDateFormat The date to be used in the results of the timeline
37	*/
38	protected string $isoDateFormat = 'L';
39
40	/**
41	* Combines statistics within the same timestamp data into a timeline.
42	* Useful for the dashboard charts.
43	*/
44	public function build(): array
45	{
46	foreach ($this->metrics as $name => $metric) {
47	$statistics = ($metric['results'] ?? []);
48	foreach ($statistics as $statistic) {
49	if ($this->hasRow($statistic->timestamp) === false) {
50	$this->createRow($statistic->timestamp);
51	}
52
53	$this->addMetricToRow($this->timeline[$statistic->timestamp], $name, $statistic);
54	}
55	}
56
57	return $this->getTimelineRows();
58	}
59
60	/**
61	* Set the date format to be used in the results of the timeline.
62	*/
63	public function setDateFormat(string $format): self
64	{
65	$this->isoDateFormat = $format;
66
67	return $this;
68	}
69
70	/**
71	* Sets the metrics that should be included in a timeline item
72	* @param array<string, array{
73	* name: string,
74	* label: string,
75	* statistics?: TimelineStatistics,
76	* results?: Collection\|TimelineDTO[],
77	* useInTimeline: bool,
78	* }> $metrics
79	*/
80	public function setMetrics(array $metrics): self
81	{
82	$this->metrics = $metrics;
83
84	return $this;
85	}
86
87	/**
88	* Returns the timeline without preserving keys.
89	*/
90	public function getTimelineRows(): array
91	{
92	return array_values($this->timeline);
93	}
94
95	/**
96	* Returns a row on the given timestamp
97	*/
98	protected function getRow(int $datestamp): ?array
99	{
100	return $this->timeline[$datestamp] ?? null;
101	}
102
103	/**
104	* Checks if a row exists on the given timestamp
105	*/
106	protected function hasRow(int $datestamp): bool
107	{
108	return ($this->getRow($datestamp) !== null);
109	}
110
111	/**
112	* Creates a row for the given timestamp. Each key in the metrics is a property.
113	* This uses the $metrics to create a row which contains a property for
114	* every metric with an initial value of 0.
115	*/
116	protected function createRow(int $timestamp): array
117	{
118	$date = Carbon::createFromTimestampMs($timestamp)->setTimezone(wp_timezone());
119
120	$row = [
121	'timestamp' => $timestamp,
122	'label' => $date->isoFormat($this->isoDateFormat),
123	];
124
125	// initialize the properties for each metric, these are the keys of the metrics
126	foreach ($this->metrics as $property => $metric) {
127	$row[$property] = 0.0;
128	}
129
130	return $this->addRowToTimeline($timestamp, $row);
131	}
132
133	/**
134	* Inserts a row to the timeline
135	*/
136	protected function addRowToTimeline(int $timestamp, array $row): array
137	{
138	$this->timeline[$timestamp] = $row;
139
140	return $this->timeline[$timestamp];
141	}
142
143	/**
144	* Adds a metric (Visits / PageViews / etc.) to the row
145	*/
146	protected function addMetricToRow(array &$row, string $metric, TimelineDTO $statistic): void
147	{
148	$row[$metric] = $statistic->amount;
149	}
150	}
151