404-solution / includes / view-build / ViewReadServiceInterface.php

ViewReadServiceInterface.php in 404 Solution 4.3.0, at includes/view-build/ViewReadServiceInterface.php

189 lines 6.1 KB

Raw Download Zip

1	<?php
2
3	if (!defined('ABSPATH')) {
4	exit;
5	}
6
7	/**
8	* Public surface of the admin view-read service.
9	*
10	* This was previously expressed as five segregated sub-interfaces
11	* (status-counts, list-read, snapshot-read, metadata, hits-lifecycle)
12	* aggregated by this composite. The segregation was never realized: every
13	* typed caller (DataAccess delegate, View, admin tables, REST/AJAX handlers,
14	* the extraction tests) depended on this composite, and no code ever depended
15	* on a narrow sub-interface. The sub-interfaces were therefore unrealized
16	* scaffolding and have been collapsed into this single interface. The method
17	* set is unchanged, so existing typed callers continue to compile.
18	*
19	* Methods are grouped by their former sub-interface for readability:
20	* - status counts + invalidation hooks
21	* - redirect-list reads (admin tables / export)
22	* - schema / capacity introspection + failure diagnostics
23	* - hits-table lifecycle hook
24	*/
25	interface ABJ_404_Solution_ViewReadServiceInterface {
26	const SORT_READINESS_READY = 'ready';
27	const SORT_READINESS_BACKFILL_PENDING = 'backfill-pending';
28	const SORT_READINESS_SCHEMA_UNAVAILABLE = 'schema-unavailable';
29
30	/* ---- status counts + invalidation hooks ---- */
31
32	/**
33	* @param bool $bypassCache
34	* @return array<string, int>
35	*/
36	public function getRedirectStatusCounts($bypassCache = false): array;
37
38	/**
39	* @param bool $bypassCache
40	* @return array<string, int>
41	*/
42	public function getCapturedStatusCounts($bypassCache = false): array;
43
44	/** @return int */
45	public function getHighImpactCapturedCount(): int;
46
47	/** @return string */
48	public function buildHighImpactCapturedCountQuery(): string;
49
50	/**
51	* @template T
52	* @param callable():T $work
53	* @return T
54	*/
55	public function runWithDeferredInvalidation(callable $work);
56
57	/** @return void */
58	public function invalidateStatusCountsCache(): void;
59
60	/** @return void */
61	public function invalidateViewSnapshotCache(): void;
62
63	/** @return void */
64	public function clearRegexRedirectsCache(): void;
65
66	/* ---- redirect-list reads (admin tables / export) ---- */
67
68	/**
69	* @param int $logID
70	* @return int
71	*/
72	public function getLogsCount($logID);
73
74	/** @return array<int, array<string, mixed>> */
75	public function getRedirectsAll();
76
77	/** @param string $tempFile @return void */
78	public function doRedirectsExport(string $tempFile): void;
79
80	/** @return array<int, array<string, mixed>> */
81	public function getRedirectsWithLogs();
82
83	/** @return array<int, array<string, mixed>> */
84	public function getRedirectsWithRegEx();
85
86	/** @return array<int, array<string, mixed>> */
87	public function getManualRedirectsWithRegexMetachars();
88
89	/**
90	* @param string $sub
91	* @param array<string, mixed> $tableOptions
92	* @return array<int\|string, mixed>
93	*/
94	public function getRedirectsForView($sub, $tableOptions);
95
96	/**
97	* Whether the most recent getRedirectsForView() result is NOT a trustworthy
98	* "genuinely empty" listing (pending build, errored read, or an empty
99	* snapshot contradicting the live source count).
100	*
101	* @return bool
102	*/
103	public function lastRedirectsViewReadWasIncomplete(): bool;
104
105	/**
106	* @param string $sub
107	* @param array<string, mixed> $tableOptions
108	* @return int
109	*/
110	public function getRedirectsForViewCount(string $sub, array $tableOptions): int;
111
112	/**
113	* Whether ordering the admin list by $orderby can be served index-ordered now
114	* (a narrow sort-key-backed sort whose column exists and whose backfill latch
115	* is set; non-key-backed sorts are always ready). The admin header uses this
116	* to disable the URL / Destination sort links on the captured tab during the
117	* post-upgrade backfill window.
118	*
119	* @param string $orderby UI orderby alias (url, final_dest, logshits, ...).
120	* @return bool
121	*/
122	public function isSortReadyForOrderby(string $orderby): bool;
123
124	/**
125	* Readiness status for ordering the admin list by $orderby. Sort-key-backed
126	* URL / Destination sorts can be ready, temporarily pending a backfill, or
127	* structurally unavailable because the backing column/index schema is absent.
128	* Non-key-backed sorts are always ready.
129	*
130	* @param string $orderby UI orderby alias (url, final_dest, logshits, ...).
131	* @return string One of the SORT_READINESS_* constants.
132	*/
133	public function sortReadinessStatusForOrderby(string $orderby): string;
134
135	/**
136	* Backfill progress (0..100) for $orderby's narrow sort key, for the admin
137	* "building the index" tooltip. Cheap: cursor wp_options read over an O(1)
138	* MAX(id) probe, never a COUNT over the captured rows.
139	*
140	* @param string $orderby UI orderby alias.
141	* @return int
142	*/
143	public function sortBackfillPercentForOrderby(string $orderby): int;
144
145	/**
146	* @param array<int, string> $postIDs
147	* @return array<int, mixed>
148	*/
149	public function getExtraDataToPermalinkSuggestions(array $postIDs): array;
150
151	/* ---- schema / capacity introspection + failure diagnostics ---- */
152
153	/** @return array<string, mixed> */
154	public function getTableEngines();
155
156	/** @return bool */
157	public function isMyISAMSupported(): bool;
158
159	/** @return int */
160	public function getCapturedCount();
161
162	/** @return array<int, string> */
163	public function getAllPostTypes();
164
165	/** @return int */
166	public function getLogDiskUsage();
167
168	/**
169	* @param array<int, int> $types
170	* @param int $trashed
171	* @return int
172	*/
173	public function getRecordCount($types = array(), $trashed = 0);
174
175	/**
176	* @param string $sub
177	* @param string $failedQuery
178	* @param array<string, mixed> $tableOptions
179	* @param array<string, mixed> $queryResult
180	* @return array<string, mixed>
181	*/
182	public function captureViewQueryFailureDiagnostics(string $sub, string $failedQuery, array $tableOptions, array $queryResult): array;
183
184	/* ---- hits-table lifecycle hook ---- */
185
186	/** @return void */
187	public function maybeUpdateRedirectsForViewHitsTable(): void;
188	}
189