1	<?php
2
3	/**
4	* Interface for database drivers.
5	*
6	* This Source Code Form is subject to the terms of the Mozilla Public License,
7	* v. 2.0. If a copy of the MPL was not distributed with this file, You can
8	* obtain one at https://mozilla.org/MPL/2.0/.
9	*
10	* @package   phpMyFAQ
11	* @author    Johannes Schlüter <johannes@php.net>
12	* @author    Thorsten Rinne <thorsten@phpmyfaq.de>
13	* @copyright 2007-2026 phpMyFAQ Team
14	* @license   https://www.mozilla.org/MPL/2.0/ Mozilla Public License Version 2.0
15	* @link      https://www.phpmyfaq.de
16	* @since     2007-08-19
17	*/
18
19	declare(strict_types=1);
20
21	namespace phpMyFAQ\Database;
22
23	use SensitiveParameter;
24
25	/**
26	* Interface DatabaseDriver
27	*
28	* @package phpMyFAQ\Database
29	*/
30	interface DatabaseDriver
31	{
32	/**
33	* Connects to the database server.
34	*
35	* @param string $host Hostname
36	* @param string $user Username
37	* @param string $password Password
38	* @param string $database Database name
39	* @return null|bool true, if connected, otherwise false
40	*/
41	public function connect(
42	string $host,
43	string $user,
44	#[SensitiveParameter]
45	string $password,
46	string $database = '',
47	?int $port = null,
48	): ?bool;
49
50	/**
51	* This function sends a query to the database.
52	*
53	* Returns a driver-specific result handle (object or resource) on success,
54	* `true` for result-less statements, or `false`/`null` on failure.
55	*
56	* @return object|resource|bool|null
57	*/
58	public function query(string $query, int $offset = 0, int $rowcount = 0): mixed;
59
60	/**
61	* Sends a parameterized query to the database. Use `?` as the positional
62	* placeholder; values are bound by the driver and never interpolated into
63	* the SQL string. Prefer this over query() + escape() for any query that
64	* carries user input.
65	*
66	* @param array<int, string|int|float|null> $params
67	* @return object|resource|bool|null
68	*/
69	public function queryPrepared(string $query, array $params): mixed;
70
71	/**
72	* Escapes a string for use in a query.
73	*/
74	public function escape(string $string): string;
75
76	/**
77	* Fetch a result row as an object.
78	*
79	* Returns a row as a `stdClass` whose properties are the selected columns,
80	* or a falsy value (`false`/`null`) once the result set is exhausted.
81	*
82	* @return \stdClass|false|null
83	*/
84	public function fetchObject(mixed $result): mixed;
85
86	/**
87	* Fetch a result row as an array.
88	*
89	* @param mixed $result
90	* @return array|false|null
91	*/
92	public function fetchArray(mixed $result): array|false|null;
93
94	/**
95	* Fetch a result row.
96	*/
97	public function fetchRow(mixed $result): mixed;
98
99	/**
100	* Fetches a complete result as a list of row objects.
101	*
102	* @return list<\stdClass>|null
103	*/
104	public function fetchAll(mixed $result): ?array;
105
106	/**
107	* Number of rows in a result.
108	*/
109	public function numRows(mixed $result): int;
110
111	/**
112	* Logs the queries.
113	*/
114	public function log(): string;
115
116	/**
117	* This function returns the table status.
118	*
119	* @param string $prefix Table prefix
120	*/
121	public function getTableStatus(string $prefix = ''): array;
122
123	/**
124	* Returns the next ID of a table.
125	*
126	* @param string $table The name of the table
127	* @param string $column The name of the column
128	*/
129	public function nextId(string $table, string $column): int;
130
131	/**
132	* Returns the error string.
133	*/
134	public function error(): string;
135
136	/**
137	* Returns the library version string.
138	*/
139	public function clientVersion(): string;
140
141	/**
142	* Returns the library version string.
143	*/
144	public function serverVersion(): string;
145
146	/**
147	* Returns an array with all table names.
148	*
149	* @param string $prefix Table prefix
150	* @return string[]
151	*/
152	public function getTableNames(string $prefix = ''): array;
153
154	/**
155	* Closes the connection to the database.
156	*/
157	public function close();
158
159	/**
160	* Returns the number of rows affected by the last INSERT, UPDATE, or DELETE query.
161	*/
162	public function affectedRows(): int;
163
164	/**
165	* Returns the ID of the last inserted row or sequence value.
166	*/
167	public function lastInsertId(): int|string;
168
169	/**
170	* Return an SQL expression that yields current datetime in the local timezone.
171	* The actual SQL value may be of SQL datetime type (or timestamp or similar),
172	* or it may be varchar/text (as is in SQLite3) - so make sure the consumer
173	* code doesn't depend on the actual type.
174	*
175	* @return string String that you can pass to SQL as in: SELECT <result of phpMyFAQ\DatabaseDriver->now()>
176	*/
177	public function now(): string;
178	}