beauty-framework/database

Beauty Database

1.0.0 2025-06-08 18:12 UTC

Requires

• php: >=8.1
• ext-pdo: *

Requires (Dev)

• phpunit/phpunit: ^12.3@dev

MIT

• database
• db
• beauty

README

Lightweight, driver-based database module for the Beauty Framework. This package provides a flexible and extendable way to connect and interact with various relational databases through a ConnectionInterface, factory/strategy-based driver resolution, and a centralized ConnectionRegistry.

Features

• PSR-compatible database access abstraction
• PDO-based drivers with automatic DSN resolution
• Out-of-the-box support for SQLite, PostgreSQL, MySQL, SQL Server (sqlsrv)
• Centralized connection registry with named connections
• Fully testable with in-memory SQLite
• Custom drivers support via strategy pattern
• Ability to fully replace PDO with any implementation via ConnectionInterface

Installation

composer require beauty-framework/database

Usage

1. Define your database configuration

return [
    'default' => 'pgsql',

    'connections' => [
        'pgsql' => [
            'driver' => 'pgsql',
            'host' => '127.0.0.1',
            'port' => 5432,
            'database' => 'app',
            'username' => 'user',
            'password' => 'secret',
        ],

        'sqlite' => [
            'driver' => 'sqlite',
            'database' => ':memory:',
        ],
    ],
];

2. Register connections in your container

$factory = new ConnectionFactory([
    new PdoPgsqlDriver(),
    new PdoMysqlDriver(),
    new PdoSqliteDriver(),
    new PdoSqlsrvDriver(),
]);

$registry = new ConnectionRegistry($config['connections'], $factory, $config['default']);

$container->instance(ConnectionFactory::class, $factory);
$container->instance(ConnectionRegistry::class, $registry);
$container->instance(ConnectionInterface::class, $registry->get());

3. Use the connection

/** @var ConnectionInterface $connection */
$connection = $container->get(ConnectionInterface::class);

$connection->execute("INSERT INTO users (name) VALUES (?)", ['Kirill']);
$users = $connection->query("SELECT * FROM users");

Supported Drivers

Driver	PDO Driver	Notes
pgsql	pgsql	PostgreSQL
mysql	mysql	MySQL / MariaDB
sqlite	sqlite	File-based or in-memory
sqlsrv	sqlsrv	SQL Server via Microsoft ext

Writing a Custom Driver

To register a new driver:

1. Implement Beauty\Database\Connection\Drivers\DriverInterface

class CustomDriver implements DriverInterface 
{
    public function supports(string $driver): bool {
        return $driver === 'mydb';
    }

    public function make(array $config): ConnectionInterface {
        // return your own Connection implementation
    }
}

1. Register it into ConnectionFactory:

$factory = new ConnectionFactory([
    new MyCustomDriver(),
]);

Replacing PDO: Custom ConnectionInterface

The ConnectionInterface only requires the following contract:

interface ConnectionInterface 
{
    public function query(string $sql, array $bindings = []): mixed;
    public function select(string $sql, array $bindings = []): array;
    public function insert(string $sql, array $bindings = []): bool;
    public function update(string $sql, array $bindings = []): int;
    public function delete(string $sql, array $bindings = []): int;
    public function transaction(callable $callback): mixed;
    public function raw(string $sql): bool;
}

You can implement your own logic (e.g., HTTP-based DBs, gRPC, NoSQL emulation) by returning your own ConnectionInterface from a driver.

Testing

A full test suite is included using PHPUnit. Use SQLite in-memory for fast isolation:

<php>
    <env name="DB_CONNECTION" value="sqlite"/>
    <env name="DB_DATABASE" value=":memory:"/>
</php>

$connection = $container->get(ConnectionInterface::class);
$connection->execute("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)");

License

MIT