README

English | Español

EasyPHPDBCore

Lightweight PDO-based database layer for PHP, with a simple CRUD Model and prepared statements everywhere.

Requirements

• PHP 8.2 or higher
• Composer
• PDO with the pdo_mysql driver (for the MySQL/MariaDB connection)

Runtime dependency: psr/log. A PSR-3 logger is optional; without one, errors are simply thrown as exceptions.

Installation

composer require hstanleycrow/easyphpdbcore

Quick example

use hstanleycrow\EasyPHPDBCore\Model;
use hstanleycrow\EasyPHPDBCore\Connection\MySQLEnvConfig;
use hstanleycrow\EasyPHPDBCore\Connection\MySQLPDOConnection;
use hstanleycrow\EasyPHPDBCore\Connection\MySQLEnvCharsetConfig;

require 'vendor/autoload.php';

// $_ENV must hold DATABASE_HOST, DATABASE_NAME, DATABASE_USERNAME,
// DATABASE_PASSWORD, DATABASE_PORT and DATABASE_CHARSET.
$connection = new MySQLPDOConnection(
    new MySQLEnvConfig($_ENV),
    new MySQLEnvCharsetConfig($_ENV)
);

class User extends Model
{
    protected ?string $table = 'users';
}

$user = new User($connection);

$id = $user->create([
    'name' => 'Harold',
    'username' => 'hstanleycrow',
    'active' => 'S',
])->lastInsertId();

$record = $user->getById($id);

$user->update(['name' => 'Harold Crow'], ['id' => $id]);

$user->delete(['id' => $id]);

Every write uses prepared statements with bound values, so array keys become column names and array values become bound parameters. Never interpolate user input into query() strings; pass it through the bindings instead.

Custom read queries

getRecords() accepts positional or named bindings:

class User extends Model
{
    protected ?string $table = 'users';

    public function getActive(): array
    {
        return $this->query('SELECT id, name FROM users WHERE active = ? ORDER BY id')
            ->getRecords(['S']);
    }
}

Optional logging

Any PSR-3 logger can be injected as the last constructor argument of the connection and the model (or the record classes). When omitted, a NullLogger is used and failures are only thrown.

$logger = new Monolog\Logger('app');
$logger->pushHandler(new Monolog\Handler\StreamHandler('php://stderr'));

$connection = new MySQLPDOConnection(new MySQLEnvConfig($_ENV), new MySQLEnvCharsetConfig($_ENV), $logger);
$user = new User($connection, $logger);

Error handling

All failures throw typed exceptions instead of printing anything:

• hstanleycrow\EasyPHPDBCore\Exception\ConnectionException — connection/config errors.
• hstanleycrow\EasyPHPDBCore\Exception\QueryException — query execution errors.

Both extend hstanleycrow\EasyPHPDBCore\Exception\DatabaseException, so you can catch either one specifically or the base class for all database errors.

Public API

Model

Connection

Record classes (used internally by Model, usable standalone)

CreateRecords, ReadRecords, UpdateRecords, DeleteRecords each expose an execute(...) method and share the same (IConnection, string $table, ?LoggerInterface) constructor shape (ReadRecords takes the query instead of a table).

Testing

composer install
composer test

The test suite runs against an in-memory SQLite database, so no MySQL server is required.

License

MIT — see LICENSE.