404-solution / includes / LogsRepositoryInterface.php

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

186 lines 5.8 KB

Raw Download Zip

1	<?php
2
3	if (!defined('ABSPATH')) {
4	exit;
5	}
6
7	/**
8	* Public contract for log insertion, querying, hits rebuild, GDPR, and lookup operations.
9	*
10	* Extracted from DataAccess in Phase 3 of the DataAccess refactor. Callers that
11	* need log insertion, log querying, GDPR anonymization, hits-table lifecycle,
12	* or lookup-table operations program against this interface.
13	*/
14	interface ABJ_404_Solution_LogsRepositoryInterface {
15
16	// =========================================================================
17	// Log data population and querying (from DataAccessTrait_Logs)
18	// =========================================================================
19
20	/**
21	* Populate logshits / logsid / last_used on each row from the pre-aggregated
22	* wp_abj404_logs_hits rollup.
23	*
24	* @param array<int, array<string, mixed>> $rows
25	* @return array<int, array<string, mixed>>
26	*/
27	public function populateLogsData($rows);
28
29	/**
30	* @return array<int, string>
31	*/
32	public function getDistinctLoggedUrls(): array;
33
34	/**
35	* @param string $specificURL
36	* @return array<int, array<string, mixed>>
37	*/
38	public function getLogsIDandURL($specificURL = '');
39
40	/**
41	* @param string $specificURL
42	* @param string\|int $limitResults
43	* @return array<int, array<string, mixed>>
44	*/
45	public function getLogsIDandURLLike($specificURL, $limitResults);
46
47	/**
48	* @param array<string, mixed> $tableOptions orderby, paged, perpage, etc.
49	* @return array<int, array<string, mixed>>
50	*/
51	public function getLogRecords($tableOptions);
52
53	/**
54	* @param int $days Number of days (default 30, clamped to 1-90)
55	* @return array<int, array<string, mixed>>
56	*/
57	public function getDailyActivityTrend(int $days = 30): array;
58
59	// =========================================================================
60	// GDPR / privacy (from DataAccessTrait_Logs)
61	// =========================================================================
62
63	/**
64	* @param string $lkupValue
65	* @param int $page
66	* @param int $perPage
67	* @return int[]
68	*/
69	public function getLogsv2IdsForLookupValue($lkupValue, $page = 1, $perPage = 100);
70
71	/**
72	* @param string $lkupValue
73	* @param int $page
74	* @param int $perPage
75	* @return array<int, array<string, mixed>>
76	*/
77	public function getLogsv2RowsForLookupValue($lkupValue, $page = 1, $perPage = 50);
78
79	/**
80	* @param int[] $ids
81	* @return bool
82	*/
83	public function anonymizeLogsv2RowsByIds($ids);
84
85	// =========================================================================
86	// Log insertion and queue (from DataAccessTrait_Logs)
87	// =========================================================================
88
89	/**
90	* @param string $requested_url
91	* @param string $action
92	* @param string $matchReason
93	* @param string\|null $requestedURLDetail
94	* @param list<array{step: string, outcome: string, detail: string}>\|null $pipelineTrace
95	* @return void
96	*/
97	public function logRedirectHit(string $requested_url, string $action, string $matchReason, ?string $requestedURLDetail = null, ?array $pipelineTrace = null): void;
98
99	/**
100	* @param array<string, mixed> $entry
101	* @return void
102	*/
103	public function queueLogEntry(array $entry): void;
104
105	/** @return void */
106	public function flushLogQueue(): void;
107
108	// =========================================================================
109	// Lookup table (from DataAccessTrait_Logs)
110	// =========================================================================
111
112	/**
113	* @param string $valueToInsert
114	* @return int
115	*/
116	public function insertLookupValueAndGetID($valueToInsert);
117
118	/**
119	* @param string $userName
120	* @return int
121	*/
122	public function getLookupIDForUser($userName);
123
124	/** @return void */
125	public function correctDuplicateLookupValues(): void;
126
127	// =========================================================================
128	// Pipeline trace (from DataAccessTrait_Logs, static)
129	// =========================================================================
130
131	/**
132	* @param string\|null $raw
133	* @return array<int, array{step: string, outcome: string, detail: string}>\|null
134	*/
135	public static function decompressPipelineTrace(?string $raw): ?array;
136
137	// =========================================================================
138	// Hits table rebuild (from DataAccessTrait_LogsHitsRebuild)
139	// =========================================================================
140
141	/** @return void */
142	public function recordLogsHitsRollupStalenessSignal(): void;
143
144	/** @return bool */
145	public function hitsTableNeedsRebuild();
146
147	/**
148	* @return int\|null Unix timestamp of last update, or null if table doesn't exist
149	*/
150	public function getLogsHitsTableLastUpdated();
151
152	/** @return string */
153	public function getLogsHitsTableLastUpdatedHuman();
154
155	/** @return bool */
156	public function createRedirectsForViewHitsTable(): bool;
157
158	// =========================================================================
159	// Hits table lifecycle (from DataAccessTrait_ViewQueriesHitsLifecycle)
160	// =========================================================================
161
162	/** @return bool */
163	public function logsHitsTableExists();
164
165	/** @return void */
166	public function scheduleHitsTableRebuild(): void;
167
168	/** @return int */
169	public function getMaxLogId();
170
171	/** @return int */
172	public function getMinLogId();
173
174	/** @return int */
175	public function getStoredMaxLogId();
176
177	/** @return int\|null */
178	public function getLogsHitsTableLastCheckedAt();
179
180	/** @return int\|null */
181	public function getLogsHitsTableLastScheduledAt();
182
183	/** @return string */
184	public function getLogsHitsTableLastDecision(): string;
185	}
186