Improved PDO interface

1.2.1 2015-08-13 23:47 UTC

This package is not auto-updated.

Last update: 2021-05-12 23:33:23 UTC


Ever found yourself thinking PDO would be a lot nicer if the API was tweaked just a little bit?

If so, PDOK may be for you. PDOK provides classes that should be almost completely compatible with PDO and PDOStatement, but with some enhancements:

  • Fluent interface
  • Connect on demand, not on instantiation
  • Disconnect and reconnect
  • Serialize, unserialize, clone support
  • Consistent method names (PDO->execute(), PDOStatement->exec())
  • Shorthand fetch methods: fetchAssoc, fetchNum
  • Iteration support - every fetch method has a corresponding each method which returns an iterator.

If you already use PDO::ERRMODE_EXCEPTION, this should work as a drop-in replacement. Please familiarise yourself with the :ref:`caveats` and :ref:`limitations` sections if you are migrating an existing project.

Requires PHP 5.4 or greater, works with HHVM.


Fluent interface for PDOStatement (even when using persistent connections):

$pdo = new \PDOK\Connector('sqlite::memory:');
$pdo->prepare('SELECT * FROM mytable WHERE mycol=?')->execute(['yep'])->fetchAll();

Fluent interface for PDO:

    ->execute('INSERT INTO foo VALUES(1, "yep");')
    ->execute('INSERT INTO foo VALUES(2, "yay");')

PDO::ERRMODE_EXCEPTION is always used:

$pdo = new \PDOK\Connector('sqlite::memory:');
try {
    $pdo->query("SOLOCT blergh FRAM gorgle");
catch (\PDOException $e) {
    echo "KABOOM!";

Connect on demand:

$pdo = new \PDOK\Connector('...')
assert($pdo->isConnected() == false);

$pdo->query("SELECT * FROM mytable");
assert($pdo->isConnected() == true);

Or you can force the connection yourself:

$pdo = new \PDOK\Connector('...');
assert($pdo->isConnected() == true);

Disconnect, reconnect, clone and serialize:

assert($pdo->isConnected() == false);

$cloned = clone $pdo;
assert($pdo->isConnected() == true && $cloned->isConnected() == false);

$unserialized = unserialize(serialize($pdo));
assert($unserialized->isConnected() == false);

Array-based static constructor:

$ini = <<<INI
dsn = "mysql:host=localhost"
user = "myuser"
pass = "mypass"
db = "hello"
statements[] = "SET NAMES \"utf8\""

$settings = parse_ini_string($ini);
$pdo = \PDOK\Connector::create($settings);

Method naming consistency (choose your poison, but stick to it):

$pdo->exec('SELECT * FROM mytable');
$pdo->execute('SELECT * FROM mytable');


Query count:

$pdo->execute('UPDATE mytable1 SET foo=1');
$pdo->execute('UPDATE mytable2 SET bar=1');
$pdo->prepare("UPDATE mytable3 SET baz=1")->execute();
assert($pdo->queries == 3);

Shorthand fetch methods:

$stmt = $connector->query("SELECT * FROM mytable");

// equivalent

// equivalent

Every fetch method has a corresponding each method:

foreach ($stmt->eachAssoc() as $row) {
    // stuff
foreach ($stmt->eachNum() as $row) {
    // stuff
foreach ($stmt->each(\PDO::FETCH_ASSOC) as $row) {
    // stuff

Interfaces! If you want to make your own statement class, implement PDOK\StatementInterface and use PDOK\StatementTrait:

class MyStatement implements \PDOK\StatementInterface
    use \PDOK\StatementTrait;

    /* ... */


  • Many methods return boolean on failure instead of being fluent. This is a decision that hasn't been made yet - I'm leaning towards them raising exceptions instead of returning false as error messages like "Tried to call function execute() on a non object" is not exactly developer friendly.


  • PDOK should be backward compatible with vanilla PDO provided you do not use type hints. You can replace your existing PDO type hints with a call to PDOK\Functions::ensurePDO($pdo), and your existing PDOStatement hints with PDOK\Functions::ensureStatement($stmt).
  • PDOK does not connect on demand. If your code requires that a connection be established on instantiation, you will need to modify it to call PDOK\Connector->connect() directly afterwards.