← All changes | app/Support/Builders/StatsTimelineBuilder.php +150 -0 2.0.1 → 2.1.1 View file →

		@@ -1,0 +1,150 @@
	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	+}