### Зачем? Зачем очередная обёртка, спросите вы? А вот зачем: * Удобный 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-специфичных опций (но за описаниями лучше залезьте в код).