1: <?php
2: /**
3: * This file contains the declaration of the interface IRecordsetManager for working with record sets.
4: *
5: * @package Database
6: *
7: * @author Oleg Schildt
8: */
9:
10: namespace SmartFactory\Interfaces;
11:
12: use \SmartFactory\DatabaseWorkers\DBWorkerException;
13:
14: /**
15: * Interface for working with record sets.
16: *
17: * @author Oleg Schildt
18: */
19: interface IRecordsetManager
20: {
21: /**
22: * Sets the dbworker to be used for working with the database.
23: *
24: * @param \SmartFactory\DatabaseWorkers\DBWorker $dbworker
25: * The dbworker to be used for working with the database.
26: *
27: * @return void
28: *
29: * @see IRecordsetManager::getDBWorker()
30: *
31: * @author Oleg Schildt
32: */
33: public function setDBWorker(\SmartFactory\DatabaseWorkers\DBWorker $dbworker): void;
34:
35: /**
36: * Returns the dbworker to be used for working with the database.
37: *
38: * @return ?\SmartFactory\DatabaseWorkers\DBWorker
39: * Returns the dbworker to be used for working with the database.
40: *
41: * @see IRecordsetManager::getDBWorker()
42: *
43: * @author Oleg Schildt
44: */
45: public function getDBWorker(): ?\SmartFactory\DatabaseWorkers\DBWorker;
46:
47: /**
48: * Defines the field mappings for working with record sets based on a table.
49: *
50: * @param string $table
51: * The name of the table.
52: *
53: * @param array $fields
54: * The array of fields in the form "field name" => "field type".
55: *
56: * @param array $key_fields
57: * The array of key fields. These are the fields that are used
58: * to uniquely identify a record.
59: *
60: * @return void
61: *
62: * @see IRecordsetManager::describeTableFieldsQuery()
63: *
64: * @author Oleg Schildt
65: */
66: public function describeTableFields(string $table, array $fields, array $key_fields): void;
67:
68: /**
69: * Defines the field mappings for working with record sets based on a query.
70: *
71: * @param array $fields
72: * The array of fields in the form "field name" => "field type".
73: *
74: * @param array $key_fields
75: * The array of key fields. These are the fields that are used
76: * to uniquely identify a record.
77: *
78: * @return void
79: *
80: * @see IRecordsetManager::describeTableFields()
81: *
82: * @author Oleg Schildt
83: */
84: public function describeTableFieldsQuery(array $fields, array $key_fields): void;
85:
86: /**
87: * Loads a record into an array in the form "field_name" => "value" based on a table.
88: *
89: * @param array &$record
90: * The target array where the data should be loaded.
91: *
92: * @param array|string $where_clause
93: * The where clause that should restrict the result. If an array of keys is passed,
94: * the where clause is build automatically based on it.
95: *
96: * @return void
97: *
98: * @see IRecordsetManager::saveRecord()
99: * @see IRecordsetManager::loadRecordSet()
100: * @see IRecordsetManager::loadRecordQuery()
101: *
102: * @uses \SmartFactory\DatabaseWorkers\DBWorker
103: *
104: * @author Oleg Schildt
105: */
106: public function loadRecord(array &$record, array|string $where_clause): void;
107:
108: /**
109: * Loads a record into an array in the form "field_name" => "value" based on a query.
110: *
111: * @param array &$record
112: * The target array where the data should be loaded.
113: *
114: * @param string $query
115: * The query to be used.
116: *
117: * @return void
118: *
119: * @see IRecordsetManager::loadRecord()
120: * @see IRecordsetManager::loadRecordSetQuery()
121: *
122: * @uses \SmartFactory\DatabaseWorkers\DBWorker
123: *
124: * @author Oleg Schildt
125: */
126: public function loadRecordQuery(array &$record, string $query): void;
127:
128: /**
129: * Deletes records by a given where clause.
130: *
131: * @param array|string $where_clause
132: * The where clause for the records to be deleted. If an array of keys is passed,
133: * the where clause is build automatically based on it.
134: *
135: * @return void
136: *
137: * @see IRecordsetManager::saveRecord()
138: * @see IRecordsetManager::deleteRecordsQuery()
139: *
140: * @uses \SmartFactory\DatabaseWorkers\DBWorker
141: *
142: * @author Oleg Schildt
143: */
144: public function deleteRecords(array|string $where_clause): void;
145:
146: /**
147: * Deletes records by a given query.
148: *
149: * @param string $query
150: * The query to be used.
151: *
152: * @return void
153: *
154: * @see IRecordsetManager::deleteRecords()
155: *
156: * @uses \SmartFactory\DatabaseWorkers\DBWorker
157: *
158: * @author Oleg Schildt
159: */
160: public function deleteRecordsQuery(string $query): void;
161:
162: /**
163: * Saves a record from an array in the form "field_name" => "value" into the table.
164: *
165: * @param array &$record
166: * The source array with the data to be saved.
167: *
168: * @param array|string $where_clause
169: * The where clause that should be used to define whether a record should be inserted or updated. If an array of keys is passed,
170: * the where clause is build automatically based on it.
171: *
172: * @param string $identity_field
173: * The name of the identity field if exists. If the identity field is specified
174: * and the record does not exist yet in the table, the source array is extended
175: * with a pair "identity field" => "identity value" issued by the database by this
176: * insert operation.
177: *
178: * @return void
179: *
180: * @see IRecordsetManager::loadRecord()
181: * @see IRecordsetManager::saveRecordSet()
182: * @see IRecordsetManager::deleteRecords()
183: *
184: * @uses \SmartFactory\DatabaseWorkers\DBWorker
185: *
186: * @author Oleg Schildt
187: */
188: public function saveRecord(array &$record, array|string $where_clause, string $identity_field = ""): void;
189:
190: /**
191: * Saves records from an array in the form
192: * $records["key_field1"]["key_field2"]["key_fieldN"]["field_name"] = "value" into the table.
193: *
194: * @param array $records
195: * The source array with the data to be saved.
196: *
197: * @param array $parent_values
198: * If this recordset is a child subset of data to be saved, you can set the values of the foreign keys
199: * in the form "field_name" => "value".
200: *
201: * @param string $identity_field
202: * The name of the identity field if exists. If the identity field is specified
203: * and the record does not exist yet in the table, the source array is extended
204: * with a pair "identity field" => "identity value" issued by the database by this
205: * insert operation.
206: *
207: * @return void
208: *
209: * @see IRecordsetManager::loadRecordSet()
210: * @see IRecordsetManager::saveRecord()
211: *
212: * @uses \SmartFactory\DatabaseWorkers\DBWorker
213: *
214: * @author Oleg Schildt
215: */
216: public function saveRecordSet(array $records, array $parent_values = [], string $identity_field = ""): void;
217:
218: /**
219: * Counts records based on the where clause.
220: *
221: * @param array|string $where_clause
222: * The where clause that should restrict the result. If an array of keys is passed,
223: * the where clause is build automatically based on it.
224: *
225: * @return int
226: * Returns the number of records.
227: *
228: * @see IRecordsetManager::countRecordsQuery()
229: *
230: * @uses \SmartFactory\DatabaseWorkers\DBWorker
231: *
232: * @author Oleg Schildt
233: */
234: public function countRecords(array|string $where_clause): int;
235:
236: /**
237: * Counts records based on the query.
238: *
239: * @param string $query
240: * The query to be used.
241: *
242: * @return int
243: * Returns the number of records.
244: *
245: * @see IRecordsetManager::countRecords()
246: *
247: * @uses \SmartFactory\DatabaseWorkers\DBWorker
248: *
249: * @author Oleg Schildt
250: */
251: public function countRecordsQuery(string $query): int;
252:
253: /**
254: * Loads records into an array in the form
255: *
256: * $records["key_field1"]["key_field2"]["key_fieldN"]["field_name"] = "value"
257: *
258: * based on a table.
259: *
260: * @param array &$records
261: * The target array where the data should be loaded.
262: *
263: * @param array|string $where_clause
264: * The where clause that should restrict the result. If an array of keys is passed,
265: * the where clause is build automatically based on it.
266: *
267: * @param int $limit
268: * The limit how many records should be loaded. 0 for unlimited.
269: *
270: * @param string $order_clause
271: * The order clause to sort the results.
272: *
273: * @return void
274: *
275: * @see IRecordsetManager::loadRecord()
276: * @see IRecordsetManager::saveRecordSet()
277: * @see IRecordsetManager::loadRecordSetQuery()
278: *
279: * @uses \SmartFactory\DatabaseWorkers\DBWorker
280: *
281: * @author Oleg Schildt
282: */
283: public function loadRecordSet(array &$records, array|string $where_clause, string $order_clause = "", int $limit = 0): void;
284:
285: /**
286: * Loads records into an array in the form
287: *
288: * $records["key_field1"]["key_field2"]["key_fieldN"]["field_name"] = "value"
289: *
290: * based on a query.
291: *
292: * @param array &$records
293: * The target array where the data should be loaded.
294: *
295: * @param string $query
296: * The query to be used.
297: *
298: * @return void
299: *
300: * @see IRecordsetManager::loadRecordSet()
301: * @see IRecordsetManager::loadRecordQuery()
302: *
303: * @uses \SmartFactory\DatabaseWorkers\DBWorker
304: *
305: * @author Oleg Schildt
306: */
307: public function loadRecordSetQuery(array &$records, string $query): void;
308:
309: /**
310: * Starts the translation.
311: *
312: * @return void
313: *
314: * @throws DBWorkerException
315: * It might throw an exception in the case of any errors.
316: *
317: * @see IRecordsetManager::commit_transaction()
318: * @see IRecordsetManager::rollback_transaction()
319: *
320: * @author Oleg Schildt
321: */
322: public function start_transaction(): void;
323:
324: /**
325: * Commits the translation.
326: *
327: * @return void
328: *
329: * @throws DBWorkerException
330: * It might throw an exception in the case of any errors.
331: *
332: * @see IRecordsetManager::start_transaction()
333: * @see IRecordsetManager::rollback_transaction()
334: *
335: * @author Oleg Schildt
336: */
337: public function commit_transaction(): void;
338:
339: /**
340: * Rolls back the translation.
341: *
342: * @throws DBWorkerException
343: * It might throw an exception in the case of any errors.
344: *
345: * @return void
346: *
347: * @see IRecordsetManager::start_transaction()
348: * @see IRecordsetManager::commit_transaction()
349: *
350: * @author Oleg Schildt
351: */
352: public function rollback_transaction(): void;
353:
354: /**
355: * Escapes the string so that it can be used in the query without causing an error.
356: *
357: * @param string $str
358: * The string to be escaped.
359: *
360: * @return string
361: * Returns the escaped string.
362: *
363: * @see IRecordsetManager::format_date()
364: * @see IRecordsetManager::format_datetime()
365: *
366: * @author Oleg Schildt
367: */
368: public function escape(string $str): string;
369:
370: /**
371: * Formats the date to a string compatible for the corresponding database.
372: *
373: * @param int $date
374: * The date value as timestamp.
375: *
376: * @return string
377: * Returns the string representation of the date compatible for the corresponding database.
378: *
379: * @see IRecordsetManager::escape()
380: * @see IRecordsetManager::format_datetime()
381: *
382: * @author Oleg Schildt
383: */
384: public function format_date(int $date): string;
385:
386: /**
387: * Formats the date/time to a string compatible for the corresponding database.
388: *
389: * @param int $datetime
390: * The date/time value as timestamp.
391: *
392: * @return string
393: * Returns the string representation of the date/time compatible for the corresponding database.
394: *
395: * @see IRecordsetManager::escape()
396: * @see IRecordsetManager::format_date()
397: *
398: * @author Oleg Schildt
399: */
400: public function format_datetime(int $datetime): string;
401: } // IRecordsetManager