404-solution / includes / stats / StatsRepositoryInterface.php

StatsRepositoryInterface.php in 404 Solution trunk, at includes/stats/StatsRepositoryInterface.php

134 lines 4.2 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	* The placeholder implementation used by legacy construction paths lives in
15	* {@see ABJ_404_Solution_UnavailableStatsRepository}.
16	*/
17	interface ABJ_404_Solution_StatsRepositoryInterface {
18
19	// =========================================================================
20	// Core stats queries
21	// =========================================================================
22
23	/**
24	* @param string $query
25	* @param array<int\|string, mixed> $valueParams
26	* @return int
27	*/
28	public function getStatsCount($query, array $valueParams);
29
30	/**
31	* @param int $sinceTimestamp
32	* @param string $notFoundDest
33	* @return array{
34	* disp404:int,
35	* distinct404:int,
36	* visitors404:int,
37	* refer404:int,
38	* redirected:int,
39	* distinctredirected:int,
40	* distinctvisitors:int,
41	* distinctrefer:int
42	* }
43	*/
44	public function getPeriodicStatsSummary($sinceTimestamp, $notFoundDest = '404');
45
46	/**
47	* @param string $notFoundDest
48	* @return array{
49	* today:array<string,int>,
50	* month:array<string,int>,
51	* year:array<string,int>,
52	* all:array<string,int>
53	* }
54	*/
55	public function getPeriodicStatsSummariesCached($notFoundDest = '404');
56
57	// =========================================================================
58	// Dashboard snapshot
59	// =========================================================================
60
61	/**
62	* @param bool $allowStale
63	* @return array{refreshed_at:int,hash:string,data:array<string, mixed>}
64	*/
65	public function getStatsDashboardSnapshot($allowStale = true);
66
67	/**
68	* @param bool $force
69	* @return array{refreshed_at:int,hash:string,data:array<string, mixed>}
70	*/
71	public function refreshStatsDashboardSnapshot($force = false);
72
73	// =========================================================================
74	// Log timestamp
75	// =========================================================================
76
77	/** @return int */
78	public function getEarliestLogTimestamp();
79
80	// =========================================================================
81	// Match-confidence distribution
82	// =========================================================================
83
84	/**
85	* Redirect-row counts grouped into match-confidence bands for the stats
86	* page. NULL score = manual; scored rows are high/medium/low per
87	* {@see ABJ_404_Solution_ScoreThresholds}.
88	*
89	* @return array{high:int,medium:int,low:int,manual:int,avg:float\|null,total:int}\|null
90	* Band counts plus rounded average score, or null on query failure.
91	*/
92	public function getConfidenceBandCounts();
93
94	// =========================================================================
95	// Email digest
96	// =========================================================================
97
98	/**
99	* @param int $limit
100	* @return array<int, array<string, mixed>>
101	*/
102	public function getTopCapturedForDigest(int $limit): array;
103
104	/**
105	* @param int $limit
106	* @return string
107	*/
108	public function buildTopCapturedForDigestQuery(int $limit): string;
109
110	/**
111	* @return array{total_captured: int, total_manual: int, total_auto: int}
112	*/
113	public function getDigestSummaryStats(): array;
114
115	/** @return int */
116	public function getCapturedCountForNotification(): int;
117
118	// =========================================================================
119	// Content keywords (permalink cache)
120	// =========================================================================
121
122	/**
123	* @param int $limit
124	* @return array<int, object>
125	*/
126	public function getPostsNeedingContentKeywords(int $limit = 500): array;
127
128	/**
129	* @param array<int, string> $idToKeywords
130	* @return void
131	*/
132	public function bulkUpdateContentKeywords(array $idToKeywords): void;
133	}
134