PHP Luminova: Database Connection Drivers and Interface Overview

Luminova provides built-in database drivers that implement the core interface for executing queries, preparing statements, and retrieving results. These drivers abstract the low-level database operations behind a consistent interface.

To get started with real-world usage, refer to the Database Examples.

Usages

Recommended

The preferred way to manage database connections in Luminova is via the Database Connection Class. It supports advanced features such as sharding, connection pooling, retry attempts, and fallback connections. It also allows easy switching between drivers by simply updating the .env value for database.connection—no code changes needed.

use Luminova\Database\Connection;

$enableConnectionPool = true; // Enable connection pooling
$maxConnectionPools = 5;      // Maximum number of pooled connections
$autoConnect = true;          // Automatically connect on initialization

$conn = new Connection($enableConnectionPool, $maxConnectionPools, $autoConnect);

Manual Driver Initialization

You can also initialize a specific driver manually if you need more control.

MySQLi Driver

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

$mysqli = new MysqliDriver(new Database([
    // connection configuration options...
]));

$mysqli->connect();

PDO Driver

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

$pdo = new PdoDriver(new Database([
    // connection configuration options...
]));

$pdo->connect();

Note:Manual driver usage does not support connection pooling, fallback connections, sharding or retry attempts.And must explicitly call connect method to establish connection.

Emulate Prepares

Emulate Prepares allows you to reuse the same named placeholder multiple times within a SQL query, a feature not natively supported by MySQLi.

While PDO supports this behavior through its own emulation, MySQLi does not. However, Luminova's database layer supports emulate prepares for both PDO and MySQLi, providing consistent behavior across drivers.

To enable or disable emulate prepares:

• Set the .env key: database.emulate.prepares
• Or define it in your configuration array using the emulate_prepares key.

When Enabled:

You can reuse placeholders like this:

use Luminova\Database\Connection;

$db = (new Connection())->database();

$stmt = $db->prepare('
    SELECT * FROM users 
    WHERE id = :identifier OR email = :identifier
');

$result = $stmt->execute(['identifier' => 100]);

Using the Database Builder

You can also use the Builder class for the same query:

$result = Builder::query('
    SELECT * FROM users 
    WHERE id = :identifier OR email = :identifier
')->execute(['identifier' => 100]);

When Disabled:

The same query will fail with an error like:

The number of variables must match the number of parameters in the prepared statement.

Luminova will internally expand the query and parameters to ensure compatibility with the driver.

This feature is especially useful for queries involving multiple comparisons with the same value.Use it when building dynamic queries or conditions across columns.

Class Definition

• Namespaces:

  • Luminova\Database\Drivers\MysqliDriver
  • Luminova\Database\Drivers\PdoDriver

• Implements:Luminova\Interface\DatabaseInterface

Methods

constructoror

Initialize database driver constructor for configurations.

This constructor allows you to initialize driver with database configuration object to later establish a connection with.

public __constructor(Luminova\Foundation\CoreDatabase $config)

Parameters:

connect

Establish a database connection.

This method allows you to open a database connection for selected driver with database configurations.

public connect(): bool

Return Value:

bool - Return true if database connection was established, otherwise false.

Throws:

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

isConnected

Check if the database is connection is already established.

public isConnected(): bool

Return Value:

bool - Returns true if connected, false otherwise.

isStatement

Determine Whether the executed query prepared statement is ready.

public isStatement(): bool

Return Value:

bool - Return true if is a prepared statement, false otherwise.

isResult

Determine Whether the executed query result is ready.

public isResult(): bool

Return Value:

bool - Return true if query result, false otherwise.

getDriver

Get the driver version name of the database connection driver.

This method will retrieve the database driver name in use (e.g sqlite, mysql, cubrid etc...).

public getDriver(): ?string

Return Value:

string|null - Returns the driver version name if the 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_version (string): The PDO driver version 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_prepares (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 raw database connection instance (e.g., PDO or MySQLi).

public raw(): ?Luminova\Interface\ConnInterface

Return Value:

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

getStatement

Retrieve the last executed prepared statement.

public getStatement(): PDOStatement|mysqli_stmt|null

Return Value:

PDOStatement|mysqli_stmt|null - Returns the statement object, or null if no statement exists.

setDebug

Sets the debug mode.

public setDebug(bool $debug): Luminova\Interface\DatabaseInterface

Return Value:

DatabaseInterface - Returns the instance of database driver interface.

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

Prepares an SQL statement for execution.

This method initializes a prepared statement for both PDO and MySQLi drivers. The query should contain placeholders (:columnName) to be bound later using bind() or param().

public prepare(string $query): Luminova\Interface\DatabaseInterface

Parameters:

Return Value:

DatabaseInterface - Returns the instance of database driver interface.

Throws:

• Luminova\Exceptions\DatabaseException - If no database connection is established.

Example:

Preparing SQL Statement:

use Luminova\Database\Connection;

$db = (new Connection())->database();

$stmt = $db->prepare("SELECT * FROM users WHERE id = :id");
$stmt->bind(':foo', 'bar');
$stmt->execute();

$result = $stmt->fetch();

query

Executes an SQL query without binding or placeholders.

This method is used for executing raw SQL statements that do not require parameter binding, such as DDL operations (CREATE, ALTER, DROP) or direct SELECT queries.

public query(string $query): Luminova\Interface\DatabaseInterface

Parameters:

Return Value:

DatabaseInterface - Returns the instance of database driver interface.

Throws:

• Luminova\Exceptions\DatabaseException - If no database connection is established.

Example:

Query Examples:

use Luminova\Database\Connection;

$db = (new Connection())->database();

// select query
$stmt = $db->query("SELECT * FROM users");
$result = $stmt->fetchAll();

// Create a new table
$result = $db->query("CREATE TABLE logs (id INT AUTO_INCREMENT PRIMARY KEY, message TEXT)")
    ->rowCount();

exec

Executes an SQL statement without placeholders and returns the number of affected rows.

This method is useful for operations like ALTER, CREATE, DELETE, where you need to know how many rows were modified.

public exec(string $query): int

Parameters:

Return Value:

int - Returns the number of rows affected by the query.

Throws:

• Luminova\Exceptions\DatabaseException - If no database connection is established.

Example:

Using the exec method.

use Luminova\Database\Connection;

$db = (new Connection())->database();

$affected = $db->exec("UPDATE users SET status = 'active' WHERE last_login > NOW() - INTERVAL 30 DAY");
echo "Updated {$affected} rows.";

beginTransaction

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

Flags:

For MySQLi:

• MYSQLI_TRANS_START_READ_ONLY: Set transaction as read-only.For PDO:
• Specify 4 to create a read-only isolation level.

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

Parameters:

Return Value:

bool - Returns true if the transaction and optional savepoint were successfully started.

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 if any.

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 - Returns true if the rollback 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.

Throws:

• Luminova\Exceptions\DatabaseException - Throw if an called when no connection is established.

getType

Determines the appropriate database parameter type for a given value.

This is used to bind parameters correctly when preparing SQL statements, returning either a PDO type constant (string) or a MySQLi type constant (int), depending on the driver context.

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

Parameters:

Return Value:

string|int - Return the parameter type, a string for PDO or an integer for MySQLi.

bind

Binds a value to a named parameter for use in a prepared statement.

This method works for both PDO and MySQLi drivers. For PDO, the binding is done via bindValue(), while for MySQLi, the value is stored in an internal array for later binding.

public bind(string $param, mixed $value, ?int $type = null): Luminova\Interface\DatabaseInterface

Parameters:

Return Value:

DatabaseInterface - Returns the instance of database driver interface.

Throws:

• Luminova\Exceptions\DatabaseException - If called without a prepared statement.

Example:

Supported in both PDO and MySQLi:

use Luminova\Database\Connection;

$db = (new Connection())->database();

$stmt = $db->prepare("SELECT * FROM users WHERE id = :id");
$stmt->bind(':id', 123)->execute();

value

Binds a value to a named parameter for use in a prepared statement.

This method is an alias of bind().

public value(string $param, mixed $value, ?int $type = null): Luminova\Interface\DatabaseInterface

Parameters:

Return Value:

DatabaseInterface - Returns the instance of database driver interface.

Throws:

• Luminova\Exceptions\DatabaseException - If called without a prepared statement.

param

Binds a variable to a named parameter by reference use in a prepared statement.

Unlike bind() and value(), this method binds the parameter by reference, which means changes to the variable will be reflected in the query execution. This is useful for scenarios where values might change before execution.

For PDO, the method binds using bindParam(), while for MySQLi, it stores a reference in an internal array.

public param(string $param, mixed &$value, ?int $type = null): Luminova\Interface\DatabaseInterface

Parameters:

Return Value:

DatabaseInterface - Returns the instance of database driver interface.

Throws:

• Luminova\Exceptions\DatabaseException - If called without a prepared statement.

Example:

For both PDO and MySQLi:

use Luminova\Database\Connection;

$db = (new Connection())->database();

$stmt = $db->prepare("UPDATE users SET status = :status WHERE id = :id");

$status = 'active';
$stmt->param(':status', $status)
    ->param(':id', $userId);

// Changing the variable before execution affects the query
$status = 'inactive';
$stmt->execute();

execute

Executes the prepared statement.

If parameters are provided, they will be bound to the statement during execution. This method works for both PDO and MySQLi drivers.

public execute(?array<string,mixed> $params = null): bool

Parameters:

Return Value:

bool - Returns true on success or false on failure.

Throws:

• Luminova\Exceptions\DatabaseException - If execution fails due to a database error.

Example:

Executing Using Prepared Statement:

use Luminova\Database\Connection;

$db = (new Connection())->database();

$stmt = $db->prepare("INSERT INTO users (name, email) VALUES (:name, :email)");
$stmt->execute([
    ':name' => 'John Doe', 
    ':email' => '[email protected]'
]);

var_dump($stmt->rowCount());

ok

Check if the last query execution was successful.

public function ok(): bool;

Return Value:

bool - Returns true on success, false on failure.

Example:

Checking Execution status:

use Luminova\Database\Connection;

$db = (new Connection())->database();

$stmt = $db->prepare("SELECT * users WHERE id = :id");
$stmt->bind('id', 100);
$stmt->execute();

$result = null;

if($stmt->ok()){
    $result = $stmt->fetchAll();
}

rowCount

Get the number of rows affected by the last executed statement.

public rowCount(): int

Return Value:

int - Returns the number of affected rows.

fetchNext

Fetch the next row from the result set as an object or array.

Alias getNext().

public fetchNext(int $mode = FETCH_OBJ): array|object|false

Parameters:

Return Value:

array|object|false - Returns the next row as an object or array, or false if no more rows are available.

fetchAll

Fetch all rows from the result set as an array of objects or arrays.

Alias getAll().

public fetchAll(int $mode = FETCH_OBJ): array|object|bool

Parameters:

Return Value:

array|object|false - Returns an array of result objects or arrays, an empty array if no rows are found or false.

getInt

Fetch the result set as a 2D array of integers.

public getInt(): array

Return Value:

array - Returns a 2D array of integers, or an empty array if no results are found.

getCount

Get the total count of selected rows as an integer.

public getCount(): int

Return Value:

int - Returns the total row count, or 0 if no results are found.

getColumns

Retrieve a specific column or multiple columns from the result set.

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 data from the result set using a specified fetch mode.

Return Modes

• RETURN_ALL to retrieve all rows at once,
• RETURN_NEXT to fetch a single row,
• RETURN_STREAM to fetch rows one at a time (use in while loops).

public fetch(int $returnMode = RETURN_ALL, int $fetchMode = FETCH_OBJ): mixed

Parameters:

Return Value:

mixed - Return the fetched result(s) based on the specified type and mode.

Throws:

• Luminova\Exceptions\DatabaseException - Throws an exception if an error occurs.

fetchObject

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

public fetchObject(?\T<string> $class = null, mixed ...$arguments): ?object

Parameters:

Return Value:

\T<object>|null - Returns the fetched object, or null if an error occurs.

Throws:

• Luminova\Exceptions\DatabaseException - If an error occurs.

Example:

Define your user model class.

Note: This fetchObject doesn't strictly require class to extend Luminova\Base\BaseModel.It can be any class.

// /app/Models/User.php

namespace App\Models;

use Luminova\Base\BaseModel;

class User extends BaseModel
{
    public string $name = '';
    public string $email = '';
    private ?string $password = null;

    public function __construct(string $password)
    {
        $this->password = $password;
    }
}

Execute query and return instance of User class object that resolve to result.

use Luminova\Database\Connection;

$db = (new Connection())->database();

$stmt = $db->prepare("SELECT name, email users WHERE id = :id LIMIT 1");
$stmt->bind('id', 100);
$stmt->execute();

$user = null;

if($stmt->ok()){
    $user = $stmt->fetchObject(User::class, 'user-password');
    echo $user->name;
}

getLastInsertId

Get the ID of the last inserted row or sequence value.

public getLastInsertId(?string $name = null): mixed

Parameters:

Return Value:

mixed - Returns the last inserted ID, or null/false on failure.

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 $stmt->fetchNext(...)).
• RETURN_2D_NUM: Fetch a 2D numeric array (same as $stmt->getInt()).
• RETURN_INT: Fetch a single integer value (same as $stmt->getCount()).
• RETURN_ID: Fetch the last insert ID (same as $stmt->getLastInsertId(...)).
• RETURN_COUNT: Fetch the count of affected rows (same as $stmt->rowCount()).
• RETURN_COLUMN: Fetch specific columns (same as $stmt->getColumns()).
• RETURN_ALL: Fetch all rows (same as $stmt->fetchAll($return)).
• RETURN_STMT: Return the statement object itself (same as $stmt->getStatement()).
• RETURN_RESULT: Return the query result in MySQLi or statement in PDO.

See documentation for database return modes.

public getResult(int $returnMode = RETURN_ALL, int $fetchMode = FETCH_OBJ): mixed

Parameters:

Return Value:

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

Throws:

• Luminova\Exceptions\DatabaseException - If an error occurs.

free

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

public free(): void

close

Frees up the statement cursor and closes the database connection.

public close(): void

profiling

Start recording the database query execution time for queries.

This method records the duration of a query in shared memory under the key __DB_QUERY_EXECUTION_TIME__. The stored value can later be retrieved from anywhere in your application.

Note:The profiling mechanism is built into Luminova’s database drivers.Avoid calling profiling() directly — doing so resets the internal timer.Instead, use getQueryTime() or getLastQueryTime() after a query runs.This method is intended for use only when building or extending a custom driver.

public profiling(bool $start = true, bool $finishedTransaction = false): void

Parameters:

Example:

To retrieve the last recorded query execution time from anywhere in your app:

$time = shared(
    '__DB_QUERY_EXECUTION_TIME__', /* Default key used for profiling */
    null, /* Do not override the existing value */
    0  /* Fallback if not set */
);

getQueryTime

Returns the total accumulated execution time for all queries executed so far.

This method returns the accumulated time spent on executing queries in either float or integer format, depending on the internal state of the query time.

public getQueryTime(): float|int

Return Value:

float|int - Return the total query execution time in seconds.

getLastQueryTime

Returns the execution time of the most recently executed query.

This method returns the time spent on the last query execution in either float or integer format, depending on the internal state of the query time.

public getLastQueryTime(): float|int

Return Value:

float|int - Return the last query execution time in seconds.