PHP Luminova: Database Driver Interface Specification

Database drivers Interface, provides methods for executing database queries, statement preparation, and result fetching. To get started, see Database Example.

Usages

The recommended way to connect to database in Luminova is by using the connection class Database Connection. This allow you to easily switch between different database drivers in environment configuration file (.env), without manually updating your code.

use Luminova\Database\Connection;

$connectionPool = true;
$maxConnections = 5;

$conn = new Connection($connectionPool, $maxConnections);

To manually initialize a specific database driver with application database connection configurations.

Luminova\Database\Drivers\MysqliDriver - Mysqli connection driver.

use Luminova\Database\Drivers\MysqliDriver;
use App\Config\Database as DatabaseConfig;

$mysqli = new MySqliDriver(new DatabaseConfig([
    ...
]));

Luminova\Database\Drivers\PdoDriver - PDO connection driver.

use Luminova\Database\Drivers\PdoDriver;
use App\Config\Database as DatabaseConfig;

$pdo = new PdoDriver(new DatabaseConfig([
    ...
]));

Note: Manual initialization doesn't support connection pool, fallback-connection nor retry-connection.

Class Definition

• Class namespaces: Luminova\Database\Drivers\MysqliDriver, Luminova\Database\Drivers\PdoDriver
• This class implements: \Luminova\Interface\DatabaseInterface,

constructor

Initialize database driver with application database configurations.

public __constructor(\Luminova\Base\CoreDatabase $config)

Parameters:

Throws:

• \Luminova\Exceptions\DatabaseException - If the database connection fails.

Methods

isConnected

Check if the database is connection is already established.

public isConnected(): bool

Return Value:

bool - Returns true if connected, false otherwise.

getDriver

Get database connection driver name in use (e.g sqlite, mysql, cubrid etc...).

public getDriver(): ?string

Return Value:

string|null - Return driver name if connection is open, otherwise null.

getConfig

Retrieve a specific database configuration property.

This method allows fetching configuration values related to the database connection.If the requested property does not exist, null is returned.

Available Properties:

• connection (string): The connection method, typically 'pdo' or other (default: 'pdo').
• pdo_engine (string): The PDO driver to use (e.g., 'mysql', 'sqlite', etc.) (default: 'mysql').
• charset (string): The character encoding for the connection (default: 'utf8mb4').
• sqlite_path (string|null): Path to the SQLite database file (default: null).
• production (bool): Indicates if the connection is in a production environment (default: false).
• database (string): The name of the selected database (default: '').
• persistent (bool): Whether to use persistent connections (default: true).
• socket (bool): Whether to use a Unix socket instead of TCP/IP (default: false).
• socket_path (string): The Unix socket path if socket is enabled (default: '').
• emulate_preparse (bool): Enables query emulation before execution (default: false).

public getConfig(string $property): mixed

Parameters:

Return Value:

mixed - Returns the property value if it exists, otherwise null.

raw

Get the original database connection object of PDO or mysqli database.

public raw(): ?Luminova\Interface\ConnInterface

Return Value:

\Luminova\Interface\ConnInterface|null - Returns the connection instance if connected, otherwise null.

getStatement

Retrieve Mysqli or PDO prepared statement of the last executed query.

public getStatement(): \PDOStatement|\mysqli_stmt|null

Return Value:

PDOStatement|mysqli_stmt|null - Retrieve mysqli or PDO prepared statement of the last executed query.

setDebug

Sets the debug mode.

public setDebug(bool $debug): self

Return Value:

self - Returns the current instance.

Parameters:

error

Get the error information for the last executed statement.

public error(): string

Return Value:

string - Returns the error information as a string.

errors

Get all error information.

public errors(): array

Return Value:

array - Returns an array of error information.

dumpDebug

Dump debug information for the last executed statement.

public dumpDebug(): bool

Return Value:

bool - Returns true if debug information is dumped, otherwise false.

info

Get information about the last executed statement.

public info(): array

Return Value:

array - Returns an array of statement execution information.

prepare

Prepare a statement for execution.

public prepare(string $query): self

Return Value:

self - Returns the current instance.

Parameters:

query

Execute a query without using placeholders.

public query(string $query): self

Return Value:

self - Returns the current instance.

Parameters:

exec

Execute an SQL statement and return the number of affected rows.

public exec(string $query): int

Return Value:

int - Returns the number of affected rows.

Parameters:

beginTransaction

Begins a transaction with optional read-only isolation level and SAVEPOINT for PDO.

public beginTransaction(int $flags = 0, ?string $name = null): bool

Parameters:

Return Value:

bool - Return true if transaction started successfully, otherwise false.

Throws:

• \Luminova\Exceptions\DatabaseException - Throws exception on PDO if failure to set transaction isolation level or create savepoint.

Note:

• If $flags is set to 4 in PDO, which is equivalent to MYSQLI_TRANS_START_READ_ONLY, a read-only isolation level will be established. If the transaction starts successfully, it will return true.

• If $name is specified in PDO, a SAVEPOINT will be created. If the savepoint creation is successful, the transaction will return true.

commit

Commits a transaction.

public commit(int $flags = 0, ?string $name = null): bool

Parameters:

Return Value:

bool - Returns true if the transaction was successfully committed, otherwise false.

rollback

Rolls back the current transaction or to a specific name while in PDO uses SAVEPOINT.

public rollback(int $flags = 0, ?string $name = null): bool

Parameters:

Return Value:

bool - Return true if rolled back was successful, otherwise false.

Throws:

• \Luminova\Exceptions\DatabaseException - Throws exception on PDO if failure to create SAVEPOINT.

inTransaction

Determine if there is any active transaction.

public inTransaction(): bool

Return Value:

bool - Return true if any active transaction, otherwise false.

getType

Returns the appropriate parameter type based on the value.

public static getType(mixed $value): string|int|null

Parameters:

Return Value:

string|int|null - The parameter type.

bind

Binds a value to a parameter.

public bind(string $param, mixed $value, ?int $type = null): self

Parameters:

Return Value:

self - Returns the current instance.

param

Binds a variable to a parameter.

public param(string $param, mixed &$value, ?int $type = null): self

Parameters:

Return Value:

self - Returns the current instance.

execute

Executes the prepared statement.

public execute(?array $params = null): bool

Parameters:

Return Value:

bool - Returns true on success, false on failure.

Throws:

• \Luminova\Exceptions\DatabaseException - Query statment encounter error.

ok

Check if query execution is completed successfully.

public function ok(): bool;

Return Value:

bool - Returns true on success, false on failure.

rowCount

Returns the number of rows affected by the last statement execution.

public rowCount(): int

Return Value:

int|bool - Returns the number of affected rows.

getNext

Fetches a next single row as an object or array.

public getNext(string $type = 'object'): array|object|bool

Parameters:

Return Value:

array|object|bool - The result object based on mode, otherwise return false on failure.

getAll

Fetches all rows as an array or objects.

public getAll(string $type = 'object'): array|object|bool

Parameters:

Return Value:

array|object|bool - The result object based on mode, otherwise return false on failure.

getInt

Fetches selected rows as a 2D array of integers.

public getInt(): array|false

Return Value:

array|bool - 2D array of integers else return false on failure.

getCount

Fetches total count of selected rows as integer.

public getCount(): int

Return Value:

int - Returns the total count as an integer, or 0 on failure.

getColumns

Get columns

public getColumns(int $mode = FETCH_COLUMN): array

Parameters:

Return Value:

array - Return and associative array or indexed array of columns depending on mode.

fetch

Fetch result with a specific type and mode

public fetch(string $type = 'all', int $mode = FETCH_OBJ): mixed

Parameters:

Return Value:

mixed - Return selected row item false on failure.

fetchObject

Fetches the result set as an object of the specified class or stdClass.

public fetchObject(string|null $class = 'stdClass', array $arguments = []): object|false

Parameters:

Return Value:

object|false - Returns the fetched object or false if no more rows are available or an error occurs.

getLastInsertId

Returns the ID of the last inserted record or sequence value.

public getLastInsertId(): string

Return Value:

string - The last insert ID.

getResult

Retrieves a result item based on the specified mode and return type.

This method allows flexible result retrieval using a single interface, depending on the mode and return type provided.

Available Modes:

• RETURN_NEXT: Fetch the next row (same as $db->getNext($return)).
• RETURN_2D_NUM: Fetch a 2D numeric array (same as $db->getInt()).
• RETURN_INT: Fetch a single integer value (same as $db->getCount()).
• RETURN_ID: Fetch the last insert ID (same as $db->getLastInsertId()).
• RETURN_COUNT: Fetch the count of affected rows (same as $db->rowCount()).
• RETURN_COLUMN: Fetch specific columns (same as $db->getColumns()).
• RETURN_ALL: Fetch all rows (same as $db->getAll($return)).
• RETURN_STMT: Return the statement object itself (same as $db->getStatement()).
• RETURN_RESULT: Return the query result in mysqli or statement in PDO.

public getResult(int $mode = RETURN_ALL string $return = 'object'): mixed

Parameters:

Return Value:

mixed - Return the result based on the specified mode and return type.

free

Frees up the statement cursor and sets the statement object to null.

public free(): void

close

Frees up the statement cursor and close database connection.

public close(): void