404-solution / includes / DatabaseCoreInterface.php

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

257 lines 7.9 KB

Raw Download Zip

1	<?php
2
3	if (!defined('ABSPATH')) {
4	exit;
5	}
6
7	/**
8	* Public contract for the shared database infrastructure layer.
9	*
10	* Every DAO module (RedirectsRepository, LogsRepository, etc.) receives a
11	* DatabaseCore instance through this interface. It encapsulates:
12	* - The centralized error-handling query pipeline (queryAndGetResults)
13	* - Table-name resolution and DDL introspection
14	* - Query timeouts (engine-aware: MariaDB SET STATEMENT, MySQL hints)
15	* - Error classification and infrastructure-error recovery
16	* - Connection management and reconnection
17	* - Runtime flags, admin notices, and write-block detection
18	*/
19	interface ABJ_404_Solution_DatabaseCoreInterface {
20
21	/**
22	* Execute a SQL query with full error handling, retry, and recovery.
23	*
24	* @param string $query SQL query (may contain {wp_*} table placeholders).
25	* @param array<string, mixed> $options {
26	* @type bool $log_errors Log errors (default true).
27	* @type bool $log_too_slow Log slow queries (default true).
28	* @type array $ignore_errors Error substrings to suppress.
29	* @type array $query_params Parameters for wpdb::prepare().
30	* @type bool $skip_repair Skip missing-table auto-repair.
31	* @type string $result_type ARRAY_A or OBJECT.
32	* @type int $timeout Query timeout in seconds (0 = default 60s).
33	* }
34	* @return array<string, mixed> {
35	* @type array $rows Result rows (empty array on non-SELECT).
36	* @type string $last_error MySQL error string ('' on success).
37	* @type array $last_result wpdb last_result.
38	* @type int $rows_affected Rows affected.
39	* @type int $insert_id Last INSERT ID.
40	* @type float $elapsed_time Seconds elapsed.
41	* @type bool $timed_out True when query timed out.
42	* }
43	*/
44	public function queryAndGetResults($query, $options = array()): array;
45
46	/**
47	* Execute a SELECT query that returns a single scalar value as int.
48	*
49	* @param string $query
50	* @param array<string, mixed> $options
51	* @return int
52	*/
53	public function queryScalarInt($query, $options = array()): int;
54
55	/**
56	* Replace {wp_*} table-name placeholders with actual prefixed names.
57	*
58	* @param string $query
59	* @return string
60	*/
61	public function doTableNameReplacements($query): string;
62
63	/**
64	* Get the normalized (lowercase) WordPress table prefix.
65	*
66	* @return string
67	*/
68	public function getLowercasePrefix(): string;
69
70	/**
71	* Build a fully-qualified plugin table name.
72	*
73	* @param string $tableSuffix e.g. 'abj404_redirects'
74	* @return string
75	*/
76	public function getPrefixedTableName($tableSuffix): string;
77
78	/**
79	* Get the CREATE TABLE DDL for an existing table.
80	*
81	* @param string $tableName
82	* @return string
83	*/
84	public function getCreateTableDDL($tableName): string;
85
86	/**
87	* Get the table-level default collation for an existing table.
88	*
89	* @param string $tableName
90	* @return string
91	*/
92	public function getTableCollationString(string $tableName): string;
93
94	/**
95	* Get the column-level collation for an existing character column.
96	*
97	* @param string $tableName
98	* @param string $columnName
99	* @return string
100	*/
101	public function getColumnCollationString(string $tableName, string $columnName): string;
102
103	/**
104	* Check whether a database table exists.
105	*
106	* @param string $tableName
107	* @return bool
108	*/
109	public function tableExists($tableName): bool;
110
111	/**
112	* Get column names from an actual database table.
113	*
114	* @param string $tableName
115	* @return array<int, string>
116	*/
117	public function getTableColumnNames(string $tableName): array;
118
119	/**
120	* Build a SQL-safe list from recognized_post_types option.
121	*
122	* @param array<string, mixed> $options
123	* @return string
124	*/
125	public function buildPostTypeSqlList(array $options): string;
126
127	/**
128	* Build a SQL-safe list from recognized_categories option.
129	*
130	* @param array<string, mixed> $options
131	* @return string
132	*/
133	public function buildCategorySqlList(array $options): string;
134
135	/**
136	* Set SQL session variables to allow large queries.
137	*
138	* @return void
139	*/
140	public function setSqlBigSelects(): void;
141
142	/**
143	* Classify an error as infrastructure (server-side) and handle it.
144	*
145	* @param string $errorText
146	* @return bool True if handled as infrastructure error.
147	*/
148	public function classifyAndHandleInfrastructureError(string $errorText): bool;
149
150	/**
151	* Classify a staged-build failure for the stage runner.
152	*
153	* @param int $stageNumber
154	* @param string $errorText
155	* @return string 'resumable', 'skip', 'halt', or 'rethrow'.
156	*/
157	public function classifyStageFailure(int $stageNumber, string $errorText): string;
158
159	/**
160	* @param string $errorText
161	* @return bool
162	*/
163	public function isOutOfMemoryError(string $errorText): bool;
164
165	/**
166	* Inject the clock instance for testability.
167	*
168	* @param ABJ_404_Solution_Clock $clock
169	* @return void
170	*/
171	public function setClock(ABJ_404_Solution_Clock $clock): void;
172
173	/**
174	* Set/get runtime flags (transients with option fallback).
175	*
176	* @param string $key
177	* @param mixed $value
178	* @param int $ttlSeconds
179	* @return void
180	*/
181	public function setRuntimeFlag(string $key, $value, int $ttlSeconds): void;
182
183	/**
184	* @param string $key
185	* @return mixed
186	*/
187	public function getRuntimeFlag(string $key);
188
189	/**
190	* Surface a plugin-specific admin notice about a DB issue.
191	*
192	* @param string $type
193	* @param string $message
194	* @param string $errorString
195	* @return void
196	*/
197	public function setPluginDbNotice(string $type, string $message, string $errorString = ''): void;
198
199	/**
200	* Clear the plugin DB notice only when its current type matches.
201	*
202	* @param string $type
203	* @return void
204	*/
205	public function clearPluginDbNoticeIfType(string $type): void;
206
207	/**
208	* @return bool True when a write-block cooldown is active (disk full or read-only).
209	*/
210	public function isWriteBlockActive(): bool;
211
212	/**
213	* @return bool True when non-essential DB writes should be skipped.
214	*/
215	public function shouldSkipNonEssentialDbWrites(): bool;
216
217	/**
218	* Attempt REPAIR TABLE for crashed or corrupted-key-file tables.
219	*
220	* @param string $errorMessage The MySQL error string.
221	* @return void
222	*/
223	public function repairTable(string $errorMessage): void;
224
225	/**
226	* Attempt to fix duplicate auto_increment IDs caused by ALTER TABLE resequencing.
227	*
228	* @param string $errorMessage The MySQL error string.
229	* @param string $sqlThatWasRun The SQL that triggered the error.
230	* @return void
231	*/
232	public function repairDuplicateIDs(string $errorMessage, string $sqlThatWasRun): void;
233
234	/**
235	* Auto-recover from collation mismatches by running correctCollations()
236	* then retrying the original query.
237	*
238	* @param string $query The SQL query to retry.
239	* @param array<string, mixed> $result Passed by reference; updated on successful retry.
240	* @param bool $producesRows Whether the query returns result rows.
241	* @param string $resultType wpdb output type (ARRAY_A or OBJECT).
242	* @return void
243	*/
244	public function recoverFromCollationMismatchAndRetry(
245	string $query, array &$result, bool $producesRows, string $resultType
246	): void;
247
248	/**
249	* Execute an array of SQL statements as a single transaction with deadlock retry.
250	*
251	* @param array<int, string> $statementArray
252	* @return void
253	* @throws \Exception on non-retryable failure.
254	*/
255	public function executeAsTransaction(array $statementArray): void;
256	}
257