====== Db ======

**Layer:** ''Core'' · **Source:** ''lib/core/Db.php:22'' (lines 22–519)

----
<code>
class Db implements DbInterface
</code>

This class provides a database abstraction layer using PDO with MySQL functionality.
It implements all methods defined in DbInterface for consistent database operations.

======= Docblock Metadata =======

^ Tag ^ Value ^
| ''@category'' | Core Class |
| ''@author'' | M.Noermoehammad |
| ''@license'' | MIT |
| ''@version'' | 1.0 |
| ''@since'' | Since Release 1.0 |
| ''@see'' | DbInterface |

======= Inheritance =======

^ Relation ^ Type ^ Meaning ^
| implements | [[scriptlog:lib:core:dbinterface|''DbInterface'']] | contract |

======= Constants (1) =======

^ Visibility ^ Name ^ Value ^ Line ^
| ''private'' | ''STATEMENT_CACHE_MAX'' | ''64;'' | 88 |

======= Properties (5) =======

^ Visibility ^ Type ^ Name ^ Default ^ Line ^
| ''private'' | ''?string'' | ''$caPath'' | ''null'' | 36 |
| ''private'' | ''string'' | ''$tablePrefix'' | '''''' | 43 |
| ''private'' | ''array'' | ''$knownTables'' | ''[ 'tbl_users', 'tbl_user_token', 'tbl_login_attempt', 'tbl_…'' | 50 |
| ''private'' | ''array'' | ''$statementCache'' | ''[]'' | 81 |
| ''private'' | ''?string'' | ''$tablePrefixPattern'' | ''null'' | 95 |

======= Methods (21) =======

^ Visibility ^ Method ^ Summary ^ Line ^
| public | ''__construct()'' | Constructor - Initializes the database connection if config is provided | 103 |
| public | ''setTablePrefix()'' | Set table prefix | 115 |
| public | ''getTablePrefix()'' | Get table prefix | 125 |
| public | ''setDbConnection()'' | Establishes a database connection using PDO | 139 |
| public | ''isConnected()'' | Checks if database connection is active | 170 |
| public | ''closeDbConnection()'' | Closes the database connection | 180 |
| private | ''ensureConnection()'' | Ensures database connection is established before operations | 192 |
| public | ''dbQuery()'' | Executes a database query and returns the statement | 207 |
| public | ''dbSelect()'' | Executes a SELECT query and returns results | 226 |
| private | ''prepareCached()'' | Prepare a SQL statement with table prefix applied, reusing already | 251 |
| public | ''clearStatementCache()'' | Forget all cached prepared statements. | 271 |
| public | ''dbInsert()'' | Inserts a new record into the specified table | 285 |
| public | ''dbLastInsertId()'' | Returns the last inserted ID | 316 |
| public | ''dbUpdate()'' | Updates records in the specified table | 332 |
| public | ''dbReplace()'' | Performs an INSERT or UPDATE (upsert) operation | 366 |
| public | ''dbDelete()'' | Deletes records from the specified table | 405 |
| public | ''dbTransaction()'' | Begins a transaction | 436 |
| public | ''dbCommit()'' | Commits a transaction | 448 |
| public | ''dbRollBack()'' | Rolls back a transaction | 460 |
| public | ''prepare()'' | Prepare a SQL statement with table prefix applied. | 477 |
| private | ''applyTablePrefix()'' | Apply table prefix to SQL query | 490 |


======== __construct() ========

<code>
public function __construct(array $config = [], array $options = [])
</code>

//lines 103–108 (6)//

Constructor - Initializes the database connection if config is provided

^  Parameter ^  Type ^  Default ^  Description ^
|  ''$config'' |  ''array'' |  ''[]'' |  Database configuration [DSN, username, password] |
|  ''$options'' |  ''array'' |  ''[]'' |  Additional PDO connection options |


======== setTablePrefix() ========

<code>
public function setTablePrefix(string $prefix): void
</code>

//lines 115–118 (4)//

Set table prefix

^  Parameter ^  Type ^  Default ^  Description ^
|  ''$prefix'' |  ''string'' |  //required// |  //none// |

**Returns:** ''void''


======== getTablePrefix() ========

<code>
public function getTablePrefix(): string
</code>

//lines 125–128 (4)//

Get table prefix

//Takes no parameters.//

**Returns:** ''string'' — string


======== setDbConnection() ========

<code>
public function setDbConnection(array $config = [], array $options = []): void
</code>

//lines 139–163 (25)//

Establishes a database connection using PDO

^  Parameter ^  Type ^  Default ^  Description ^
|  ''$config'' |  ''array'' |  ''[]'' |  Database configuration [DSN, username, password] |
|  ''$options'' |  ''array'' |  ''[]'' |  Additional PDO connection options |

**Returns:** ''void'' — void

**Throws:** ''\InvalidArgumentException'', ''\RuntimeException''


======== isConnected() ========

<code>
public function isConnected(): bool
</code>

//lines 170–173 (4)//

Checks if database connection is active

//Takes no parameters.//

**Returns:** ''bool'' — bool True if connected, false otherwise


======== closeDbConnection() ========

<code>
public function closeDbConnection(): void
</code>

//lines 180–184 (5)//

Closes the database connection

//Takes no parameters.//

**Returns:** ''void'' — void


======== ensureConnection() ========

<code>
private function ensureConnection(): void
</code>

//lines 192–197 (6)//

Ensures database connection is established before operations

//Takes no parameters.//

**Returns:** ''void'' — void

**Throws:** ''\RuntimeException''


======== dbQuery() ========

<code>
public function dbQuery(string $sql, array $args = []): \PDOStatement
</code>

//lines 207–214 (8)//

Executes a database query and returns the statement

^  Parameter ^  Type ^  Default ^  Description ^
|  ''$sql'' |  ''string'' |  //required// |  SQL query to execute |
|  ''$args'' |  ''array'' |  ''[]'' |  Parameters for prepared statement |

**Returns:** ''\PDOStatement'' — \PDOStatement Executed statement

**Throws:** ''\RuntimeException''


======== dbSelect() ========

<code>
public function dbSelect(string $sql, array $parameters = [], int $fetchMode = \PDO::FETCH_OBJ, string $class = &#039;&#039;): array
</code>

//lines 226–237 (12)//

Executes a SELECT query and returns results

^  Parameter ^  Type ^  Default ^  Description ^
|  ''$sql'' |  ''string'' |  //required// |  SQL SELECT query |
|  ''$parameters'' |  ''array'' |  ''[]'' |  Query parameters |
|  ''$fetchMode'' |  ''int'' |  ''\PDO::FETCH_OBJ'' |  PDO fetch mode (default: PDO::FETCH_OBJ) |
|  ''$class'' |  ''string'' |  '''''' |  Class name for PDO::FETCH_CLASS mode |

**Returns:** ''array'' — array Fetched results

**Throws:** ''\RuntimeException''


======== prepareCached() ========

<code>
private function prepareCached(string $sql): \PDOStatement
</code>

//lines 251–261 (11)//

Prepare a SQL statement with table prefix applied, reusing already

prepared statements with identical SQL text for the lifetime of the
connection (request-scoped). Bound parameters are passed via execute()
on each call, which PDO supports repeatedly on the same statement.

The cache is bounded to STATEMENT_CACHE_MAX entries; once full it is
reset so the request continues with fresh prepares.

^  Parameter ^  Type ^  Default ^  Description ^
|  ''$sql'' |  ''string'' |  //required// |  Fully-prefixed SQL query |

**Returns:** ''\PDOStatement'' — \PDOStatement


======== clearStatementCache() ========

<code>
public function clearStatementCache(): void
</code>

//lines 271–274 (4)//

Forget all cached prepared statements.

Exposed for tests and called automatically when the connection is
re-established or closed.

//Takes no parameters.//

**Returns:** ''void'' — void


======== dbInsert() ========

<code>
public function dbInsert(string $tablename, array $params): bool
</code>

//lines 285–308 (24)//

Inserts a new record into the specified table

^  Parameter ^  Type ^  Default ^  Description ^
|  ''$tablename'' |  ''string'' |  //required// |  Name of the table |
|  ''$params'' |  ''array'' |  //required// |  Associative array of column => value pairs |

**Returns:** ''bool'' — bool True on success, false on failure

**Throws:** ''\InvalidArgumentException'', ''\RuntimeException''


======== dbLastInsertId() ========

<code>
public function dbLastInsertId(): string
</code>

//lines 316–320 (5)//

Returns the last inserted ID

//Takes no parameters.//

**Returns:** ''string'' — string Last inserted row ID

**Throws:** ''\RuntimeException''


======== dbUpdate() ========

<code>
public function dbUpdate(string $tablename, array $params, array $where): int
</code>

//lines 332–352 (21)//

Updates records in the specified table

^  Parameter ^  Type ^  Default ^  Description ^
|  ''$tablename'' |  ''string'' |  //required// |  Name of the table |
|  ''$params'' |  ''array'' |  //required// |  Associative array of column => value pairs to update |
|  ''$where'' |  ''array'' |  //required// |  Associative array of conditions for WHERE clause |

**Returns:** ''int'' — int Number of affected rows

**Throws:** ''\InvalidArgumentException'', ''\RuntimeException''


======== dbReplace() ========

<code>
public function dbReplace(string $tablename, array $params, array $updateParams): bool
</code>

//lines 366–393 (28)//

Performs an INSERT or UPDATE (upsert) operation

Inserts a new record or updates existing one if duplicate key exists

^  Parameter ^  Type ^  Default ^  Description ^
|  ''$tablename'' |  ''string'' |  //required// |  Name of the table |
|  ''$params'' |  ''array'' |  //required// |  Associative array of column => value pairs for insert |
|  ''$updateParams'' |  ''array'' |  //required// |  Associative array of column => value pairs for update |

**Returns:** ''bool'' — bool True on success, false on failure

**Throws:** ''\InvalidArgumentException'', ''\RuntimeException''


======== dbDelete() ========

<code>
public function dbDelete(string $tablename, array $where, ?int $limit = null): int
</code>

//lines 405–428 (24)//

Deletes records from the specified table

^  Parameter ^  Type ^  Default ^  Description ^
|  ''$tablename'' |  ''string'' |  //required// |  Name of the table |
|  ''$where'' |  ''array'' |  //required// |  Associative array of conditions for WHERE clause |
|  ''$limit'' |  ''?int'' |  ''null'' |  Optional maximum number of rows to delete |

**Returns:** ''int'' — int Number of affected rows

**Throws:** ''\InvalidArgumentException'', ''\RuntimeException''


======== dbTransaction() ========

<code>
public function dbTransaction(): bool
</code>

//lines 436–440 (5)//

Begins a transaction

//Takes no parameters.//

**Returns:** ''bool'' — bool True on success, false on failure

**Throws:** ''\RuntimeException''


======== dbCommit() ========

<code>
public function dbCommit(): bool
</code>

//lines 448–452 (5)//

Commits a transaction

//Takes no parameters.//

**Returns:** ''bool'' — bool True on success, false on failure

**Throws:** ''\RuntimeException''


======== dbRollBack() ========

<code>
public function dbRollBack(): bool
</code>

//lines 460–464 (5)//

Rolls back a transaction

//Takes no parameters.//

**Returns:** ''bool'' — bool True on success, false on failure

**Throws:** ''\RuntimeException''


======== prepare() ========

<code>
public function prepare(string $sql, array $driverOptions = [])
</code>

//lines 477–482 (6)//

Prepare a SQL statement with table prefix applied.

Delegates to PDO::prepare() after applying the configured table prefix.
This enables legacy code (ApiAuth, API controllers) that calls
$dbc->prepare() directly to work correctly with prefixed table names.

^  Parameter ^  Type ^  Default ^  Description ^
|  ''$sql'' |  ''string'' |  //required// |  SQL query (may contain unprefixed tbl_ names) |
|  ''$driverOptions'' |  ''array'' |  ''[]'' |  Optional PDO driver options |

**Returns:** ''(none declared)'' — \PDOStatement&#124;false


======== applyTablePrefix() ========

<code>
private function applyTablePrefix(string $sql): string
</code>

//lines 490–518 (29)//

Apply table prefix to SQL query

^  Parameter ^  Type ^  Default ^  Description ^
|  ''$sql'' |  ''string'' |  //required// |  //none// |

**Returns:** ''string'' — string


----

//This page is generated from source by 'tools/gendoc'. Edits will be overwritten.//