README

A small, dependency-free database abstraction layer for PHP. initorm/dbal gives you a thin, lazily-connecting PDO wrapper and a fluent result mapper — nothing more.

It is part of the InitORM stack, but it has no runtime dependencies and can be used on its own anywhere PDO can.

Highlights

• Lazy connections. No socket is opened until the first query.
• Driver-aware DSN building. MySQL/MariaDB, PostgreSQL, SQLite.
• Fluent result mapper. asAssoc(), asObject(), asClass(), asLazy(), asArray() / asBoth().
• Type-aware binding. bool → PARAM_BOOL, int → PARAM_INT, null → PARAM_NULL, everything else → PARAM_STR.
• In-memory query log for debugging hotspots.
• PSR-3 friendly logging. Pass any LoggerInterface, a callable, a file path, or anything with a critical() method.
• Transparent PDO forwarding. Unknown method calls are forwarded to the underlying PDO / PDOStatement, so lastInsertId(), beginTransaction(), closeCursor(), etc. all work directly on the wrapper.

Installation

composer require initorm/dbal

Requirements: PHP 8.0+ and the pdo extension, plus the driver extension for the database you target (pdo_mysql, pdo_pgsql, pdo_sqlite).

60-second quick start

use InitORM\DBAL\Connection\Connection;

$db = new Connection([
    'driver'   => 'mysql',
    'host'     => '127.0.0.1',
    'port'     => 3306,
    'database' => 'shop',
    'username' => 'app',
    'password' => 'secret',
    'charset'  => 'utf8mb4',
]);

// Read
$user = $db->query('SELECT id, name FROM users WHERE id = :id', ['id' => 42])
           ->asAssoc()
           ->row();

// Write
$db->query(
    'INSERT INTO users (name, email) VALUES (:name, :email)',
    ['name' => 'Alice', 'email' => 'alice@example.com']
);
$newId = (int) $db->lastInsertId();      // forwarded to PDO

Documentation

Full docs live in docs/:

• 01 · Getting Started
• 02 · Connection
• 03 · Querying
• 04 · DataMapper
• 05 · Transactions
• 06 · Logging
• 07 · Factories & DI
• 08 · Exceptions
• 09 · Recipes

Testing

composer install
composer test

The suite runs against SQLite in-memory and finishes in well under a second.

Upgrading from 1.x

See UPGRADE.md. The notable breaking changes are: PHP ≥ 8.0, src/ layout, PDO::ATTR_PERSISTENT defaults to false, rows() returns [] instead of null when empty, and bind() returns PARAM_BOOL for booleans.

Contributing

Issues and pull requests are welcome. Please:

1. Open an issue first if you intend to make a non-trivial change.
2. Make sure composer test is green.
3. Cover new behaviour with a test under tests/.

See the organisation-wide contribution guide for the full process.

License

MIT © Muhammet ŞAFAK