Зачем?

Зачем очередная обёртка, спросите вы? А вот зачем:

• Удобный select builder по мотивам MediaWiki-овского - не то, чтобы он был везде нужен, да и параметры экранировать, в принципе, можно и через голое PDO... ...Но! Запросы часто нужно собирать по частям - и вот тут select builder на голых PHP-шных массивах очень удобен. Ну и в целом - синтаксис более краток, чем PDO. Но если не хочется - можно его и не использовать.
• Удобные функции для изменения данных - insert, upsert, update, delete, просто по имени таблицы и переданному массиву записей
• Автоматическое переподключение
• Вложенные транзакции на SAVEPOINT'ах
• Лог запросов

Я это использую во всех проектах примерно с момента знакомства с MediaWiki.

Лицензия и автор

Лицензия - GPL 3.0 или более новой версии

Автор - Виталий Филиппов, 2012-2017

Создание соединения

$db = new DatabasePdoPgsql([
    'host' => 'localhost',
    'port' => 5432,
    'socket' => '/var/run/postgresql',
    'dbname' => '',
    'username' => '',
    'password' => '',
    'reconnect' => true,
    'tableNames' => [],
    'queryLogFile' => '',
    'autoBegin' => false,
    'ondestroy' => 'commit',
    'init' => [],
]);

Опции в основном говорят сами за себя. Неочевидные:

• tableNames - маппинг имён таблиц (поддерживается замена имён таблиц на уровне обёртки).
• queryLogFile - путь к файлу с логом запросов
• autoBegin - начинать ли транзакцию автоматически при первом запросе
• ondestroy - что делать при уничтожении объекта с активной транзакцией: применить ("commit") или откатить ("rollback").

"SELECT BUILDER"

$db->select($tables, $fields, $where, $options, $format)

Пример:

$db->select(
    [
        'u' => 'users',
        'i' => [ 'INNER', 'instances', [ 'i.id=u.instance_id' ] ]
    ],
    'u.*, i.name instance_name',
    [
        'u.reg_timestamp > ?' => time(),
        'u.reg_timestamp < date_part(\'epoch\', now())',
        'u.key' => [ 'A', 'B', 'C' ], // превратится в условие: u.key IN ('A', 'B', 'C')
    ],
    [
        'FOR UPDATE', // или 'FOR SHARE' или 'LOCK IN SHARE MODE'
        'GROUP BY' => 'u.id',
        'ORDER BY' => [ 'u.reg_timestamp' => 'ASC' ],
        'LIMIT' => 10,
        'OFFSET' => 10,
    ],
    MS_HASH
);

По сути - это весь базовый синтаксис select builder'а. JOIN'ы могут быть LEFT, могут быть вложенными.

MS_* - формат возврата. По умолчанию возвращает массив записей БД в ассоциативном формате. MS_HASH - значение по умолчанию, его как 4-й параметр можно не указывать, либо вместо MS_HASH можно указать:

• MS_VALUE - тогда вернётся только 1-е значение 1-й строки (скаляр)
• MS_ROW - вернётся только 1-я строка (в ассоциативном формате)
• MS_COL - вернётся только 1-я колонка (массив скаляров)
• MS_RESULT - вернётся объект результата (mysqli/PDO) для ручной обработки, результат при этом не буферизуется

Можно вызвать $db->select("SELECT * FROM users", MS_HASH) - это просто выполнит текстовый запрос. В этом случае вторым параметром обязатело передать одну из констант MS_*.

Также вместо $db->select($tables, $fields, $where, $options) можно вызвать с теми же параметрами $db->select_builder($tables, $fields, $where, $options) - он вернёт текст запроса.

UPSERT

$db->upsert('users', [ [ 'email' => 'vasya@pupkin.ru', 'name' => 'vasya', 'surname' => 'pupkin' ] ], [ 'email' ]) - UPSERT.

Для тех, кто знает PostgreSQL - это INSERT ... ON CONFLICT (email) DO UPDATE ...

Третий параметр - список полей уникального ключа, по которым проверяет конфликт.

Для тех, кто знает MySQL - аналог REPLACE или точнее INSERT ... ON DUPLICATE KEY UPDATE ...

Другие функции

$db->quote($value) - экранирование значения

$db->query("TRUNCATE users") - выполнение произвольных запросов без чтения результата (только true/false)

$db->insert_row('users', [ 'name' => 'vasya', 'surname' => 'pupkin' ]) - вставка одной строки, вернёт ID

$db->insert('users', [ [ 'name' => 'vasya', 'surname' => 'pupkin' ], ... ]) - вставка множества строк

$db->update('users', [ 'name' => 'vasya' ], [ 'id' => 1 ]) - эквивалентно UPDATE users SET name='vasya' WHERE id=1

Плюшка: в качестве первого параметра можно передавать JOIN'енные таблицы, в PostgreSQL это будет корректно превращено в конструкцию UPDATE table FROM ...

Например:

$db->update(
    [ 'u' => 'users', 'i' => [ 'INNER', 'instances', [ 'i.id=u.instance_id'] ] ],
    'name' => 'vasya',
    [ 'i.domain' => 'pupkin.ru' ]
);

$db->delete('users', [ 'id' => [ 1, 2, 3 ] ]) - удаление по условию

В качестве первого параметра, как и в update(), можно передавать JOIN'енные таблицы, в PostgreSQL это будет корректно превращено в конструкцию DELETE ... USING.

Транзакции

$db->begin(), $db->commit(), $db->rollback(), $db->commitAll(), $db->rollbackAll()

Транзакции. Могут быть вложенные, т.е. можно несколько раз подряд сделать begin и commit/rollback. Вложенные транзакции превращаются в SAVEPOINT'ы.

$db->commitAll() коммитит транзакцию со всеми активными SAVEPOINT'ами,

$db->rollbackAll() откатывает транзакцию со всеми активными SAVEPOINT'ами.

VALUES

Дополнительная плюшка: обёртка для синтаксиса "inline таблиц" PostgreSQL.

$users = $db->select(
    [
        'd' => $db->values_table([
            [ 'social_network' => 'vk.com', 'date' => '2017-01-01' ],
            [ 'social_network' => 'facebook.com', 'date' => '2017-01-02' ],
        ]),
        'u' => [ 'INNER', 'users', [ 'u.social_network=d.social_network', 'u.reg_date=d.date' ] ],
    ],
    'u.*',
    []
);

Эквивалентно

SELECT u.*
FROM (VALUES ('vk.com','2017-01-01'),('facebook.com','2017-01-02')) AS d ("social_network","date")
INNER JOIN users u ON (u.social_network=d.social_network) AND (u.reg_date=d.date)

MySQL

Всё вышеописанное, кроме VALUES, актуально и для MySQL - синтаксис точно такой же.

Дополнительная плюшка в MySQL - это CALC_FOUND_ROWS и функция $db->found_rows(), возвращающая количество найденных строк. Фактически эту опцию можно использоать и в PdoPgsql-драйвере - он пробует эмулировать её через COUNT(*) OVER() - но это не очень красивое решение.

И ещё одна плюшка - возможность использования той же самой обёртки для общения с SphinxSearch, работающему по протоколу SphinxQL - в ней есть поддержка sphinx-специфичных опций (но за описаниями лучше залезьте в код).