PHP Luminova: Database Connection Management

Databases are crucial in application development for storing and managing data. The Luminova Database class simplifies initiating a database connection, enabling efficient data management. For a comprehensive guide, see Database Example.

With Luminova, establishing a database connection is easy and requires minimal configuration. Simply define your database host-name, username, and password in the ENV file.

To allow connections through the CLI, specify your MYSQL socket path in the ENV file using database.mysql.socket.path. For SQLITE, specify your database path and file in database.sqlite.path, such as writeable/database/production.sqlite, ensuring it is located in /writeable/database/.

Class Definition

• Class namespace: \Luminova\Database\Connection
• This class implements: \Luminova\Interface\LazyInterface, \Countable

Properties

Database connection driver instance.

protected ?\Luminova\Interface\DatabaseInterface $db = null;

Methods

constructor

Initializes a database connection based on provided parameters or default to .env configuration.

• Configures maxConnections and pool properties from the provided arguments or environment variables.
• If $pool or $max are provided, they override the corresponding environment variable values.

public __construct(?bool $pool = null, ?int $maxConnections = null)

Parameters:

Throws:

• \Luminova\Exceptions\DatabaseException - If connection retries fail, the max connection limit is exceeded, an invalid driver or driver interface is detected, or a connection error occurs.

getInstance

Retrieves the shared singleton instance of the Connection class.

public static getInstance(?bool $pool = null, ?int $maxConnections = null): self

Parameters:

Return Value:

self - Return the singleton instance of the Connection class.

Throws:

• \Luminova\Exceptions\DatabaseException - If all retry attempts fail, the maximum connection limit is reached, an invalid database driver is provided, an error occurs during connection, or an invalid driver interface is detected.

getPool

Retrieves a free connection from the pool. Optionally fetches the first available valid connection.

If $any_free is set to true, the method returns the first free connection that is connected and valid, removing it from the pool. Otherwise, it fetches the first connection in the pool and returns it if valid, or null if no valid connection exists.

public getPool(bool $any_free = false): ?\Luminova\Interface\DatabaseInterface

Parameters:

Return Value:

DatabaseInterface - Return the first valid connection from the pool or null if none are available.

newInstance

Retrieves a new database driver instance based on the provided configuration.

If no configuration is provided, the default configuration will be used.

public static newInstance(?\Luminova\Base\CoreDatabase $config = null): ?\Luminova\Interface\DatabaseInterface

Parameters:

Return Value:

DatabaseInterface|null - Return the database driver instance, or null if connection fails.

Throws:

• \Luminova\Exceptions\DatabaseException - If all retry attempts fail, the maximum connection limit is reached, an invalid database driver is provided, an error occurs during connection, or an invalid driver interface is detected.

database

Retrieves the database driver connection instance.

public database(): ?\Luminova\Interface\DatabaseInterface

Return Value:

DatabaseInterface|null - Return the driver connection instance, or null if not connected.

Usage:

To get the raw database connection instance of PDO or mysqli.

<?php 
$db = $conn->database()->raw()

connect

Connects to the database, either returning a connection instance or reusing a previous connection from the pool if available. This method also optionally retries failed connections based on the retry attempt value set in the .env configuration (database.connection.retry) or backup database connections defined withing the App\Config\Database class.

public connect(): ?\Luminova\Interface\DatabaseInterface

Return Value:

DatabaseInterface|null -Return the database driver instance (either MySqliDriver or PdoDriver), or null if connection fails.

Throws:

• \Luminova\Exceptions\DatabaseException - If all retry attempts fail, the maximum connection limit is reached, an invalid database driver is provided, an error occurs during connection, or an invalid driver interface is detected.

disconnect

Frees up the statement cursor and close current database connection.

public disconnect(): bool

Return Value:

bool - Return true if disconnected, false otherwise.

Note: To close all connections including pools use purge method instead.

retry

Attempts to reconnect to the database with optional fallback to backup servers.

If $retry is set to null, the method will attempt to connect using backup databases (if available).Otherwise, it will attempt to reconnect based on the specified retry count.

public retry(int|null $retry = 1): ?\Luminova\Interface\DatabaseInterface

Parameters:

Return Value:

DatabaseInterface|null - Returns a database connection if successful, or null if all attempts fail.

Throws:

• \Luminova\Exceptions\DatabaseException - If all retry attempts fail, the maximum connection limit is reached, an invalid database driver is provided, or an error occurs during connection.

release

Releases a connection back to the connection pool.

public release(DatabaseInterface $connection, string $id): void

Parameters:

Throws:

• \Luminova\Exceptions\DatabaseException - Throws if max connections are reached.

If the connection pool is not full, adds the provided connection to the pool else closes the provided connection.

purge

Purges all pooled connections and optionally closes the current database connection.

public purge(bool $close_current = false): bool

Parameters:

Return Value:

bool - Return true when connections are closed, otherwise false.

Note: If the conn parameter is true, the database connection will be closed; otherwise, only the pool connections will be closed.

count

Count the number of connections in pools.

public count(): int

Return Value:

int - Return the number of connection pools.