FrostMVC PHP Framework
DB
FrostMVC\DB
use FrostMVC\DB;
PDO-style wrapper around MySQLi.
Provides a familiar prepare/bind/execute/fetch API backed by MySQLi with support for named parameters (:name), deadlock retries, SSL, Unix socket connections, and connection timeouts.
Configure the active connection via DB::$db in app/settings.php.
Constants
| Constant | Value | Description |
|---|---|---|
| DB::FETCH_ASSOC | 2 |
|
| DB::FETCH_NUM | 3 |
|
| DB::ATTR_ERRMODE | 3 |
|
| DB::ERRMODE_SILENT | 0 |
|
| DB::ERRMODE_WARNING | 1 |
|
| DB::ERRMODE_EXCEPTION | 2 |
Properties
| Property | Type | Description |
|---|---|---|
| DB::$db | ?self |
Methods
| ->__construct() | Creates a new DB instance and configures connection parameters. The physical connection is deferred until the first query. |
| ->appendError() | Appends additional context to the stored error message. |
| ->beginTransaction() | Starts a database transaction. Ensures a connection is open. |
| ->bindParam() | Binds a value to a named parameter previously parsed by prepare(). Accepts the parameter by reference so late-bound values are captured. |
| ->close() | Closes the underlying MySQLi connection. |
| ->commit() | Commits the current transaction, making all changes permanent. |
| ->debug() | Returns the last prepared SQL statement with bound parameter values substituted in place of named placeholders. Intended for debugging only — do not use the output as an actual query. |
| ->errorInfo() | Returns error information about the last operation. Format mirrors PDO: [SQLSTATE, driver error code, driver error message]. |
| ->exec() | Executes a raw SQL statement without parameter binding. Suitable for DDL statements (CREATE, ALTER, DROP) that do not return a result set. Updates the affected-row count. |
| ->execute() | Executes the prepared statement with the bound parameters. Automatically retries up to 10 times on deadlock (error 1213). Optionally prepares and executes an ad-hoc statement in one call. |
| ->fetch() | Fetches a single row from the last executed statement. |
| ->fetchAll() | Fetches all rows from the last executed statement. |
| ->getCharset() | Returns the current character set name of the connection. |
| ->lastInsertId() | Returns the auto-increment ID generated by the last INSERT statement. |
| ->prepare() | Parses named parameters (:name) out of an SQL string, replacing them with positional ? placeholders understood by MySQLi, and stores the parameter names in order for subsequent bindParam() calls. |
| ->query() | Prepares and immediately executes a SQL statement, returning all rows as an associative array. Equivalent to calling prepare() then fetchAll(). |
| ->rollback() | Rolls back the current transaction, discarding all uncommitted changes. |
| ->rowCount() | Returns the number of rows affected by the last INSERT, UPDATE, or DELETE. |
| ->setAttribute() | Sets a connection attribute. Mirrors the PDO::setAttribute() interface. Supported attributes: - DB::ATTR_ERRMODE (3): accepted values are DB::ERRMODE_SILENT (0), DB::ERRMODE_WARNING (1), or DB::ERRMODE_EXCEPTION (2). |
| ->setCharset() | Sets the character set for the connection, e.g. 'utf8mb4'. The value is applied on the next (lazy) connect instead of opening a connection eagerly, so requests that never query stay connection-free. |
| ->setConnectTimeout() | Sets the maximum number of seconds to wait when establishing a connection. Useful for failing fast when the database server is unavailable. A value of 0 means no explicit timeout (OS default applies). |
| ->setDatabaseName() | Selects the active database. If a connection is already open, switches the database on the existing connection immediately. |
| ->setHost() | Sets the hostname or IP of the MySQL server. Schedules a reconnect on the next query. |
| ->setPassword() | Sets the MySQL password. |
| ->setPort() | Sets the TCP port used when connecting to the MySQL server. The standard MySQL port is 3306. |
| ->setSocket() | Sets the Unix socket path for the MySQL connection. When set, the socket is used instead of the host/port TCP connection, which is faster on servers where both PHP and MySQL run locally. |
| ->setSSL() | Configures SSL/TLS for encrypted database connections. Must be called before the first query so the options are applied on connect. |
| ->setUser() | Sets the MySQL username. |
__construct()
$dB->__construct($host = '', $user = '', $pass = '', $database = '', $port = 3306, $socket = '')
Creates a new DB instance and configures connection parameters. The physical connection is deferred until the first query.
Parameters
| $host | string |
Hostname or IP of the MySQL server. Default:'' |
| $user | string |
MySQL username. Default:'' |
| $pass | string |
MySQL password. Default:'' |
| $database | string |
Database name to select on connect. Default:'' |
| $port | int |
TCP port. Defaults to 3306. Default:3306 |
| $socket | string |
Unix socket path. Overrides host/port when set. Default:'' |
appendError()
$dB->appendError($message)
Appends additional context to the stored error message.
Parameters
| $message | string |
beginTransaction()
$dB->beginTransaction()
Starts a database transaction. Ensures a connection is open.
Returns
$this
bindParam()
$dB->bindParam($key, &$value)
Binds a value to a named parameter previously parsed by prepare(). Accepts the parameter by reference so late-bound values are captured.
Parameters
| $key | string |
The parameter name without the leading colon. |
| &$value | mixed |
The value to bind. |
close()
$dB->close()
Closes the underlying MySQLi connection.
commit()
$dB->commit()
Commits the current transaction, making all changes permanent.
debug()
$dB->debug()
Returns the last prepared SQL statement with bound parameter values substituted in place of named placeholders. Intended for debugging only — do not use the output as an actual query.
Returns
string
errorInfo()
$dB->errorInfo(): array
Returns error information about the last operation. Format mirrors PDO: [SQLSTATE, driver error code, driver error message].
Returns
array{0: string, 1: int, 2: string}
exec()
$dB->exec($cmd)
Executes a raw SQL statement without parameter binding. Suitable for DDL statements (CREATE, ALTER, DROP) that do not return a result set. Updates the affected-row count.
Parameters
| $cmd | string |
Raw SQL statement. |
execute()
$dB->execute($cmd = '', $values = [])
Executes the prepared statement with the bound parameters. Automatically retries up to 10 times on deadlock (error 1213). Optionally prepares and executes an ad-hoc statement in one call.
Parameters
| $cmd | string |
Optional SQL to prepare and execute immediately. Default:'' |
| $values | array |
Optional positional values when using $cmd. Default:[] |
Returns
bool True on success, false on failure.
fetch()
$dB->fetch($mode)
Fetches a single row from the last executed statement.
Parameters
| $mode | int |
DB::FETCH_ASSOC or DB::FETCH_NUM. |
Returns
array|false Associative or numeric array, false if no row.
fetchAll()
$dB->fetchAll($mode)
Fetches all rows from the last executed statement.
Parameters
| $mode | int |
DB::FETCH_ASSOC or DB::FETCH_NUM. |
Returns
array Array of rows, empty array if no results.
getCharset()
$dB->getCharset(): string
Returns the current character set name of the connection.
Returns
string
lastInsertId()
$dB->lastInsertId()
Returns the auto-increment ID generated by the last INSERT statement.
Returns
int|string
prepare()
$dB->prepare($cmd)
Parses named parameters (:name) out of an SQL string, replacing them with positional ? placeholders understood by MySQLi, and stores the parameter names in order for subsequent bindParam() calls.
Parameters
| $cmd | string |
SQL statement with optional :name placeholders. |
Returns
$this
query()
$dB->query($cmd)
Prepares and immediately executes a SQL statement, returning all rows as an associative array. Equivalent to calling prepare() then fetchAll().
Parameters
| $cmd | string |
SQL statement. |
Returns
array
rollback()
$dB->rollback()
Rolls back the current transaction, discarding all uncommitted changes.
rowCount()
$dB->rowCount()
Returns the number of rows affected by the last INSERT, UPDATE, or DELETE.
Returns
int
setAttribute()
$dB->setAttribute($attribute, $value)
Sets a connection attribute. Mirrors the PDO::setAttribute() interface. Supported attributes: - DB::ATTR_ERRMODE (3): accepted values are DB::ERRMODE_SILENT (0), DB::ERRMODE_WARNING (1), or DB::ERRMODE_EXCEPTION (2).
Parameters
| $attribute | int |
One of the DB::ATTR_* constants. |
| $value | int |
The value for the attribute. |
setCharset()
$dB->setCharset($charset)
Sets the character set for the connection, e.g. 'utf8mb4'. The value is applied on the next (lazy) connect instead of opening a connection eagerly, so requests that never query stay connection-free.
Parameters
| $charset | string |
setConnectTimeout()
$dB->setConnectTimeout(int $seconds)
Sets the maximum number of seconds to wait when establishing a connection. Useful for failing fast when the database server is unavailable. A value of 0 means no explicit timeout (OS default applies).
Parameters
| $seconds | int |
setDatabaseName()
$dB->setDatabaseName($dbname)
Selects the active database. If a connection is already open, switches the database on the existing connection immediately.
Parameters
| $dbname | string |
setHost()
$dB->setHost($host)
Sets the hostname or IP of the MySQL server. Schedules a reconnect on the next query.
Parameters
| $host | string |
setPassword()
$dB->setPassword($pass)
Sets the MySQL password.
Parameters
| $pass | string |
setPort()
$dB->setPort(int $port)
Sets the TCP port used when connecting to the MySQL server. The standard MySQL port is 3306.
Parameters
| $port | int |
setSocket()
$dB->setSocket(string $socket)
Sets the Unix socket path for the MySQL connection. When set, the socket is used instead of the host/port TCP connection, which is faster on servers where both PHP and MySQL run locally.
Parameters
| $socket | string |
Absolute path to the socket file, e.g. /var/run/mysqld/mysqld.sock |
setSSL()
$dB->setSSL(string $key, string $cert, string $ca, string $caPath = '', string $ciphers = '')
Configures SSL/TLS for encrypted database connections. Must be called before the first query so the options are applied on connect.
Parameters
| $key | string |
Path to the client private key file. |
| $cert | string |
Path to the client certificate file. |
| $ca | string |
Path to the CA certificate file. |
| $caPath | string |
Directory containing trusted CA certificates in PEM format. Default:'' |
| $ciphers | string |
Colon-separated list of permitted SSL ciphers. Default:'' |
setUser()
$dB->setUser($user)
Sets the MySQL username.
Parameters
| $user | string |
Generated from core/classes/DB.php (FrostMVC ).