404-solution / includes / StatsRepositoryInterface.php

StatsRepositoryInterface.php in 404 Solution 4.2.0, at includes/StatsRepositoryInterface.php

117 lines 3.5 KB

Raw Download Zip

1	<?php
2
3	if (!defined('ABSPATH')) {
4	exit;
5	}
6
7	/**
8	* Public contract for stats aggregation, dashboard snapshots, and digest data.
9	*
10	* Extracted from DataAccess in Phase 4 of the DataAccess refactor. Callers that
11	* need stats counts, periodic summaries, dashboard snapshots, digest data,
12	* or content-keyword operations program against this interface.
13	*/
14	interface ABJ_404_Solution_StatsRepositoryInterface {
15
16	// =========================================================================
17	// Core stats queries
18	// =========================================================================
19
20	/**
21	* @param string $query
22	* @param array<int\|string, mixed> $valueParams
23	* @return int
24	*/
25	public function getStatsCount($query, array $valueParams);
26
27	/**
28	* @param int $sinceTimestamp
29	* @param string $notFoundDest
30	* @return array{
31	* disp404:int,
32	* distinct404:int,
33	* visitors404:int,
34	* refer404:int,
35	* redirected:int,
36	* distinctredirected:int,
37	* distinctvisitors:int,
38	* distinctrefer:int
39	* }
40	*/
41	public function getPeriodicStatsSummary($sinceTimestamp, $notFoundDest = '404');
42
43	/**
44	* @param string $notFoundDest
45	* @return array{
46	* today:array<string,int>,
47	* month:array<string,int>,
48	* year:array<string,int>,
49	* all:array<string,int>
50	* }
51	*/
52	public function getPeriodicStatsSummariesCached($notFoundDest = '404');
53
54	// =========================================================================
55	// Dashboard snapshot
56	// =========================================================================
57
58	/**
59	* @param bool $allowStale
60	* @return array{refreshed_at:int,hash:string,data:array<string, mixed>}
61	*/
62	public function getStatsDashboardSnapshot($allowStale = true);
63
64	/**
65	* @param bool $force
66	* @return array{refreshed_at:int,hash:string,data:array<string, mixed>}
67	*/
68	public function refreshStatsDashboardSnapshot($force = false);
69
70	// =========================================================================
71	// Log timestamp
72	// =========================================================================
73
74	/** @return int */
75	public function getEarliestLogTimestamp();
76
77	// =========================================================================
78	// Email digest
79	// =========================================================================
80
81	/**
82	* @param int $limit
83	* @return array<int, array<string, mixed>>
84	*/
85	public function getTopCapturedForDigest(int $limit): array;
86
87	/**
88	* @param int $limit
89	* @return string
90	*/
91	public function buildTopCapturedForDigestQuery(int $limit): string;
92
93	/**
94	* @return array{total_captured: int, total_manual: int, total_auto: int}
95	*/
96	public function getDigestSummaryStats(): array;
97
98	/** @return int */
99	public function getCapturedCountForNotification(): int;
100
101	// =========================================================================
102	// Content keywords (permalink cache)
103	// =========================================================================
104
105	/**
106	* @param int $limit
107	* @return array<int, object>
108	*/
109	public function getPostsNeedingContentKeywords(int $limit = 500): array;
110
111	/**
112	* @param array<int, string> $idToKeywords
113	* @return void
114	*/
115	public function bulkUpdateContentKeywords(array $idToKeywords): void;
116	}
117