{"id":21888857,"url":"https://github.com/digitalstars/database","last_synced_at":"2025-04-15T10:23:54.255Z","repository":{"id":45638653,"uuid":"279421934","full_name":"digitalstars/DataBase","owner":"digitalstars","description":"Библиотека-обертка над стандартным PDO PHP для простой, удобной работы с различными базами данных и с защитой от SQL инъекций","archived":false,"fork":false,"pushed_at":"2025-01-12T17:33:41.000Z","size":56,"stargazers_count":12,"open_issues_count":0,"forks_count":7,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-03-23T09:16:04.635Z","etag":null,"topics":["database","orm","pdo-php","sql","sql-injection"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/digitalstars.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2020-07-13T22:09:20.000Z","updated_at":"2025-01-12T17:29:32.000Z","dependencies_parsed_at":"2024-02-07T11:47:33.809Z","dependency_job_id":"7a568260-b457-47c9-8c04-4c4cd658be28","html_url":"https://github.com/digitalstars/DataBase","commit_stats":{"total_commits":46,"total_committers":5,"mean_commits":9.2,"dds":"0.23913043478260865","last_synced_commit":"73d1c6ec4b33dcb8028a02c16ac616ff4a26cc26"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalstars%2FDataBase","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalstars%2FDataBase/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalstars%2FDataBase/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalstars%2FDataBase/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/digitalstars","download_url":"https://codeload.github.com/digitalstars/DataBase/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249049587,"owners_count":21204487,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","orm","pdo-php","sql","sql-injection"],"created_at":"2024-11-28T11:17:46.722Z","updated_at":"2025-04-15T10:23:54.231Z","avatar_url":"https://github.com/digitalstars.png","language":"PHP","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"DataBase logo\" title=\"DataBase это Библиотека-обертка над стандартным PDO PHP для простой, удобной работы с различными базами данных и с защитой от SQL инъекций\" src=\"http://images.vfl.ru/ii/1594995511/ead9bb36/31100317.png\"/\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://img.shields.io/packagist/php-v/digitalstars/DataBase\" alt=\"php version\"\u003e\n\u003cimg src=\"https://img.shields.io/packagist/dt/digitalstars/DataBase\" alt=\"downloads\"\u003e\n\u003cimg src=\"https://img.shields.io/github/repo-size/digitalstars/DataBase\" alt=\"repo size\"\u003e\n\u003cimg src=\"https://img.shields.io/github/license/digitalstars/DataBase\" alt=\"License\"\u003e\n\u003c/p\u003e \n\n#### Комьюнити:\n[Беседа ВК (Помощь)](https://vk.me/join/AJQ1dzQRUQxtfd7zSm4STOmt) | [Беседа ВК (Лог обновлений)](https://vk.me/join/AJQ1d37aORgoMQyc_BDK3Ka1)\n--- | --- |\n\n### Почему DataBase?\n\n* Универсальность — Благодаря тому, что DataBase наследуется от `PHP-PDO`, её можно\nиспользовать с различными БД.\n* Простота — DataBase включает в себя удобные\nзаполнители, которы серьёзно упрощают работу с SQL запросами. Также частые\nSQL запросы уже составлены и вынесены в виде методов.\n* При использовании Заполнителей, вы полностью защищены от `SQL инъекций`.\n### Функционал\nВ библиотеке поддерживается:\n * Все методы [PHP-PDO](https://www.php.net/manual/ru/book.pdo.php)\n * Свои заполнители\n * ORM конструкции\n\n### Оглавление\n* [Подключение](#Подключение)\n* [Заполнители](#что-такое-заполнители)\n* [Настройка PhpStorm](#Настройка-PhpStorm)\n* [Хандлер sql запросов](#Хандлер-sql-запросов)\n* [Типы заполнителей](#Типы-заполнителей-DataBase)\n    * [?i (int)](#i--заполнитель-целого-числа) \n    * [?d (double)](#d--заполнитель-числа-с-плавающей-точкой)\n    * [?s (string)](#s--заполнитель-строкового-типа)\n    * [?S (string) (для LIKE)](#s--заполнитель-строкового-типа-для-подстановки-в-sql-оператор-like)\n    * [?n (null)](#n--заполнитель-null-типа) \n    * [?f (field)](#f--заполнитель-имени-таблицы-или-поля)\n    * [?A* (ассоциативный массив)](#a--заполнитель-ассоциативного-множества-из-ассоциативного-массива-генерирующий-последовательность-пар-ключ--значение) \n    * [?A[?n, ?s, ?i, ?d, ...] (ассоциативный массив)](#an-s-i-d---заполнитель-ассоциативного-множества-с-явным-указанием-типа-и-количества-аргументов-генерирующий-последовательность-пар-ключ--значение) \n    * [?a* (массив)](#a--заполнитель-множества-из-простого-или-также-ассоциативного-массива-генерирующий-последовательность-значений) \n    * [?a[?n, ?s, ?i, ?d, ...] (массив)](#an-s-i-d---заполнитель-множества-с-явным-указанием-типа-и-количества-аргументов-генерирующий-последовательность-значений) \n    * [?v* (VALUES)](#v--заполнитель-values-из-простого-или-также-ассоциативного-двумерного-массива-генерирующий-последовательность-значений-для-заполнения-values) \n    * [?v[?n, ?s, ?i, ?d, ...] (VALUES)](#vn-s-i-d---заполнитель-множества-из-двумерного-массива-с-явным-указанием-типа-и-количества-аргументов-генерирующий-последовательность-значений-для-заполнения-values) \n    * [?w* (WHERE)](#w--заполнитель-ассоциативного-множества-из-ассоциативного-массива-генерирующий-последовательность-пар-ключ--значение-с-разделителем-and) \n    * [?w[?n, ?s, ?i, ?d, ...] (WHERE)](#wn-s-i-d---заполнитель-ассоциативного-множества-с-явным-указанием-типа-и-количества-аргументов-генерирующий-последовательность-пар-ключ--значение-с-разделителем-and) \n* [Дополнительные методы](#методы-orm)\n    * [getQueryString](#getquerystring--sql-string)\n    * [execCommit](#execcommit--int--false)\n    * [rows($sql, $args = [], $fetchMode = PDO::FETCH_ASSOC)](#rowssql-args---fetchmode--pdofetch_assoc--array--false)\n    * [row($sql, $args = [], $fetchMode = PDO::FETCH_ASSOC)](#rowsql-args---fetchmode--pdofetch_assoc--array--false)\n    * [getById($table, $id, $fetchMode = PDO::FETCH_ASSOC)](#getbyidtable-id-fetchmode--pdofetch_assoc--array--false)\n    * [count($sql, $args = [])](#countsql-args----int--false)\n    * [insert($table, $data)](#inserttable-data--int--false)\n    * [update($table, $data, $where = [])](#updatetable-data-where----int--false)\n    * [delete($table, $where, $limit = -1)](#deletetable-where-limit---1--int--false)\n    * [deleteAll($table)](#deletealltable--int--false)\n    * [deleteById($table, $id)](#deletebyidtable-id--int--false)\n    * [deleteByIds($table, $column, $ids)](#deletebyidstable-column-ids--int--false)\n    * [truncate($table)](#truncatetable--int--false)\n\n## Подключение\n### Используя composer\n```\ncomposer require digitalstars/database\n```\n```php\nrequire_once \"vendor/autoload.php\"; //Подключаем библиотеку\n```\n### Вручную\n1. Скачать последний релиз\n2. Подключить `autoload.php`\n\u003e Вот так будет происходить подключение, если ваш бот находится в той же папке, что и папка `DataBase-master`\n```php\nrequire_once \"DataBase-master/autoload.php\"; //Подключаем библиотеку\n```\n\n### Подключение к СуБД\n\nСинтаксис конструктора базового класса такой же, как и у PHP-PDO\n\n```php\nuse DigitalStars\\DataBase\\DB;\n\n$dsn = ''; // Имя источника данных или DSN, содержащее информацию, необходимую для подключения к базе данных. \n$login = ''; // Логин\n$pass = ''; // Пароль\n$options = []; // Массив ключ=\u003eзначение специфичных для драйвера настроек подключения. \n\n$db = new DB($dsn, $login, $pass, $options);\n```\n\n#### Пример подключения к MySQL\n\n```php\nuse DigitalStars\\DataBase\\DB;\n\n$db_type = 'mysql'; // Это может быть mysql, sybase или любой другой, в зависимости от вашей СуБД\n$db_name = 'test'; // Имя БД\n$login = 'root'; // Логин\n$pass = 'pass'; // Пароль\n$ip = 'localhost'; // Адрес\n\n// С портом по умолчанию\n$db = new DB(\"$db_type:host=$ip;dbname=$db_name\", $login, $pass);\n\n// С нестандартным портом\n$port = 1234;\n$db = new DB(\"$db_type:host=$ip;port=$port;dbname=$db_name\", $login, $pass);\n\n// Подключение с выбором кодировки UTF8\n$db = new DB(\"$db_type:host=$ip;dbname=$db_name;charset=UTF8\", $login, $pass);\n\n// Или вот так (советуем использовать этот вариант)\n$db = new DB(\"$db_type:host=$ip;dbname=$db_name;\", $login, $pass, [\n        PDO::MYSQL_ATTR_INIT_COMMAND =\u003e \"SET NAMES 'utf8'\",\n        PDO::ATTR_DEFAULT_FETCH_MODE =\u003e PDO::FETCH_ASSOC,\n        PDO::ATTR_ERRMODE =\u003e PDO::ERRMODE_EXCEPTION\n]);\n// В этом примере, сразу после подключения выполнится SQL запрос \"SET NAMES 'utf8'\"\n```\n\n#### Пример подключение к SQLite\n\n```php\nuse DigitalStars\\DataBase\\DB;\n\n$db_type = 'sqlite';\n$db_path = 'path/to/file/test.sqlite'; // Путь к файлу с базой данных\n\n// Подключение\n$db = new DB(\"$db_type:$db_path\");\n```\n\n## Что такое заполнители?\n\n**Заполнители** — специальные типизированные маркеры, которые пишутся в строке SQL запроса вместо явных значений (параметров запроса), чем упрощают читаемость кода и защищают от SQL инъекций.  \nЗаполнители поддерживаются в следующих методах:\n* exec()\n* execCommit()\n* query()\n* prepare()  \n\u003e О том как работают эти методы можно посмотреть в [PHP-PDO](https://www.php.net/manual/ru/book.pdo.php).\n\n```php\n\u003c?php\nrequire 'vendor/autoload.php';\nuse DigitalStars\\DataBase\\DB;\n\n// Соединение с СУБД SQLite и получение объекта, который включает в себя все методы PHP-PDO и библиотеки\n$db = new DB(\"sqlite:./test.sqlite\");\n\n// Получение объекта результата PDOStatement\n$result = $db-\u003equery(\"SELECT * FROM users WHERE name = ?s AND age = ?i\", [\"Василий\", 30]);\n\n// Получаем данные (в виде ассоциативного массива)\n$data = $result-\u003efetch();\n\n// Не работает запрос? Не проблема - выведите его на печать:\necho $db-\u003egetQueryString();\n```\n\n\u003e Параметры SQL-запроса, прошедшие через заполнители, обрабатываются специальными функциями экранирования, в зависимости от типа заполнителей. Т.е. вам теперь нет необходимости заключать переменные в функции экранирования типа `quote()` или приводить их к числовому типу, как это было раньше\n\n### Типы заполнителей и типы параметров SQL-запроса\n\nТипы заполнителей и их предназначение описываются ниже. Прежде чем знакомиться с типами заполнителей, необходимо понять как работает механизм библиотеки DataBase.\n\n```php\n$db-\u003equery(\"SELECT ?i\", [123]); \n```\nSQL-запрос после преобразования шаблона:\n```sql\nSELECT 123\n```\n\u003e В процессе исполнения этой команды библиотека проверяет, является ли аргумент `123` целочисленным значением. Заполнитель `?i` представляет собой символ `?` (знак вопроса) и первую букву слова `integer`. Если аргумент действительно представляет собой целочисленный тип данных, то в шаблоне SQL-запроса заполнитель `?i` заменяется на значение `123` и SQL передается на исполнение.\n\nПоскольку PHP слаботипизированный язык, то вышеописанное выражение эквивалентно нижеописанному:\n\n```php\n$db-\u003equery(\"SELECT ?i\", '123'); \n```\n \nSQL-запрос после преобразования шаблона:\n \n ```sql\nSELECT 123\n ```\n \n\u003e Т.е. числа (целые и с плавающей точкой) представленные как в своем типе, так и в виде `string` — равнозначны с точки зрения библиотеки.\n \n### Приведение к типу заполнителя\n \n```php\n$db-\u003equery(\"SELECT ?i\", '123.7'); \n```\nSQL-запрос после преобразования шаблона:\n```sql\nSELECT 123\n```\n  \nВ данном примере заполнитель целочисленного типа данных ожидает значение типа `integer`, а передается `double`.\n\nДопускаются следующие преобразования:\n\n* К типу `int` (заполнитель `?i`) приводятся:\n  * Числа с плавающей точкой, представленные как `string` или `double`\n  * `bool(true)` преобразуется в `int(1)`\n  * `bool(false)` и `null` преобразуется в `int(0)`\n* К типу `double` (заполнитель `?d`) приводятся:\n  * Целые числа, представленные как `string` или `int`\n  * `bool(true)` преобразуется в `float(1)`\n  * `bool(false)` и `null` преобразуется в `float(0)`\n* К типу `string` (заполнитель `?s`) приводятся:\n  * `numeric` преобразуется в `string`\n  * `null` преобразуется в `string(0) \"\"`\n  * `bool(true)` преобразуется в `string(1) \"1\"`\n  * `bool(false)` преобразуется в `string(1) \"0\"`\n   \u003e Это поведение отличается от приведения типа `bool` к `int` в PHP, т.к. зачастую на практике `bool` записывается в MySql именно как число.\n* Тип `null` (заполнитель `?n`) просто вставляет `NULL` в место заполнителя.  \nВходные параметры не требуются\n\n## Настройка PhpStorm\n\nДля того, что-бы IDE нормально реагировала на заполнители, и не подсвечивала места с заполнителями ошибками, необходимо\nдобавить заполнители в список пользовательских параметров.\n\nПуть диалогового окна с настройками\n\u003e File \u003e\u003e Settings... \u003e\u003e Tools \u003e\u003e Database \u003e\u003e User Parameters\n\nЗатем в окошке \"Parameter patterns\" нужно добавить следующие 2 шаблона и поставить обе галочки \"In scripts\" и \"In literals\":\n* `\\?[aAvw]\\[.*?\\]`\n* `\\?[aAvw]?[sSidnf]`\n\nОкно настройки должно выглядеть следующим образом\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"Окно настройки\" title=\"Окно настройки после завершения настройки\" src=\"http://images.vfl.ru/ii/1597246970/ab6ab795/31324661.png\"/\u003e\n\u003c/p\u003e\n\n## Хандлер sql запросов\n\nЕсли вам необходимо обрабатывать все выполняемые в скрипте SQL запросы, например для дебага.\n\n```php\n$db-\u003esetLoggerFunc(function ($query) {\n    $file = 'log.txt';\n    $query = \"Время: \".date('d.m.y H:i:s').\"\\n\".$query;\n    file_put_contents($file, $query, FILE_APPEND | LOCK_EX);\n});\n```\n\n## Типы заполнителей DataBase\n\n### `?i` — заполнитель целого числа\n\n```php\n$_POST['id'] = '123456';\n$db-\u003equery('SELECT * FROM `users` WHERE `id` = ?i', [$_POST['id']]); \n```\nSQL-запрос после преобразования шаблона:\n```sql\nSELECT * FROM `users` WHERE `id` = 123456\n```\n\u003e **ВНИМАНИЕ!** Если вы оперируете числами, выходящими за пределы `PHP_INT_MAX`, то:\n\u003e * Оперируйте ими исключительно как строками в своих программах.\n\u003e * Не используйте данный заполнитель, используйте заполнитель строки `?s` (см. ниже). Дело в том, что числа, выходящие за пределы `PHP_INT_MAX`, PHP интерпретирует как числа с плавающей точкой. Парсер библиотеки постарается преобразовать параметр к типу int, в итоге:  \n\u003e\u003e«*результат будет неопределенным, так как float не имеет достаточной точности, чтобы вернуть верный результат. В этом случае не будет выведено ни предупреждения, ни даже замечания!*» — \u003ca href=\"http://php.net/manual/ru/language.types.integer.php#language.types.integer.casting.from-float\"\u003ephp.net\u003c/a\u003e. \n\n### `?d` — заполнитель числа с плавающей точкой\n\n\u003e **ВНИМАНИЕ!** Если вы используете библиотеку для работы с типом данных `double`, установите соответствующую локаль, что бы разделитель целой и дробной части был одинаков как на уровне PHP, так и на уровне СУБД. \n\n### `?s` — заполнитель строкового типа\n\nЗначения экранируются с помощью функции PDO::quote()\n\n```php\n$db-\u003equery('SELECT ?s, ?s, ?s, ?s, ?s', [55.5, true, false, null, 'Д\"Артаньян']); \n```  \nSQL-запрос после преобразования шаблона:\n \n```sql\nSELECT \"55.5\", \"1\", \"0\", \"\", \"Д\\\"Артаньян\"\n```\n### `?S` — заполнитель строкового типа для подстановки в SQL-оператор LIKE \n\nЗначения экранируются с помощью функции PDO::quote() + экранирование спецсимволов, используемых в операторе LIKE (`%` и `_`): \n\n```php  \n$db-\u003equery('SELECT \"?S\"', '% _'); \n```  \nSQL-запрос после преобразования шаблона:\n```sql\nSELECT \"\\% \\_\"\n```\n \n### `?n` — заполнитель `NULL` типа\n\nЗаполнитель просто вставляет `NULL` в запрос, входной параметр не нужен\n\n```php\n$db-\u003equery('SELECT ?n'); \n```  \nSQL-запрос после преобразования шаблона:\n \n ```sql\nSELECT NULL\n ```\n\n### `?f` — заполнитель имени таблицы или поля\n\nДанный заполнитель предназначен для случаев, когда имя таблицы или поля передается в запросе через параметр. Значение обрамляется символом апостроф:\n\n```php\n$db-\u003equery('SELECT * FROM ?f', 'table'); \n```\nSQL-запрос после преобразования шаблона:\n```sql\nSELECT * FROM `table` \n```\n \n### `?A*` — заполнитель ассоциативного множества из ассоциативного массива, генерирующий последовательность пар `ключ = значение`\nПример: `\"key_1\" = \"val_1\", \"key_2\" = \"val_2\", ..., \"key_N\" = \"val_N\"`  \nКлючи экранируются заполнителем `?f`\n \nгде `*` после заполнителя — один из типов:\n * `i` (заполнитель целого числа)\n * `d` (заполнитель числа с плавающей точкой)\n * `s` (заполнитель строкового типа)\n * `f` (заполнитель имени таблицы или поля)\n \nПравила преобразования и экранирования такие же, как и для одиночных скалярных типов, описанных выше.\n \n```php\n$db-\u003equery('UPDATE test SET ?Ai', [\n    ['count' =\u003e 30, 'amount' =\u003e 1000, 'status' =\u003e 66]\n]);\n```\nSQL-запрос после преобразования шаблона:\n```sql\nUPDATE test SET `count` = 30, `amount` = 1000, `status` = 66\n```\n\n### `?A[?n, ?s, ?i, ?d, ...]` — заполнитель ассоциативного множества с явным указанием типа и количества аргументов, генерирующий последовательность пар `ключ = значение`\n\nПример: `\"key_1\" = \"val_1\", \"key_2\" =\u003e \"val_2\", ..., \"key_N\" = \"val_N\"`\n\n```php\n$db-\u003equery('UPDATE test SET ?A[?i, ?s, ?d]', [\n    ['count' =\u003e 30.25, 'title' =\u003e 'Какой-то заголовок', 'amount' =\u003e '66.55']\n]);\n```\nSQL-запрос после преобразования шаблона:\n```sql\nUPDATE test SET `count` = 30, `title` = 'Какой-то заголовок', `amount` = 66.55\n```\n\n### `?a*` — заполнитель множества из простого (или также ассоциативного) массива, генерирующий последовательность значений\nПример: `\"val_1\", \"val_2\", ..., \"val_N\"`\n\n где * после заполнителя — один из типов:\n * `i` (заполнитель целого числа)\n * `d` (заполнитель числа с плавающей точкой)\n * `s` (заполнитель строкового типа)\n * `f` (заполнитель имени таблицы или поля)\n \n правила преобразования и экранирования такие же, как и для одиночных скалярных типов, описанных выше.\n\n```php\n$db-\u003equery('INSERT INTO test (count, amount, status) VALUES (?ai)', [\n    [30, 1000, 66]\n]);\n```\n  SQL-запрос после преобразования шаблона:\n```sql\nINSERT INTO test (count, amount, status) VALUES (30, 1000, 66)\n```\n\n### `?a[?n, ?s, ?i, ?d, ...]` — заполнитель множества с явным указанием типа и количества аргументов, генерирующий последовательность значений\n\nПример: `\"val_1\", \"val_2\", ..., \"val_N\"`\n\n```php\n$db-\u003equery('INSERT INTO test (count, title, amount) VALUES (?a[?i, ?s, ?d])', [\n    [30.25, 'Какой-то заголовок', '66.55']\n]);\n```\n  SQL-запрос после преобразования шаблона:\n```sql\nINSERT INTO test (count, title, amount) VALUES (30, 'Какой-то заголовок', 66.55)\n```\n\n### `?v*` — заполнитель VALUES из простого (или также ассоциативного) двумерного массива, генерирующий последовательность значений для заполнения VALUES\nПример: `(\"val_1\", \"val_2\", ..., \"val_N\"), (\"val_1\", \"val_2\", ..., \"val_N\"), ...`\n\n где * после заполнителя — один из типов:\n * `i` (заполнитель целого числа)\n * `d` (заполнитель числа с плавающей точкой)\n * `s` (заполнитель строкового типа)\n * `f` (заполнитель имени таблицы или поля)\n \n правила преобразования и экранирования такие же, как и для одиночных скалярных типов, описанных выше.\n\n```php\n$db-\u003equery('INSERT INTO test (count, amount, status) VALUES ?vi', [\n    [\n        [30, 1000, 66],\n        [41, 2500, 77],\n        [25, 3211, 24]\n    ]\n]);\n```\n  SQL-запрос после преобразования шаблона:\n```sql\nINSERT INTO test (count, amount, status) VALUES (30, 1000, 66), (41, 2500, 77), (25, 3211, 24)\n```\n\n### `?v[?n, ?s, ?i, ?d, ...]` — заполнитель множества из двумерного массива с явным указанием типа и количества аргументов, генерирующий последовательность значений для заполнения VALUES\n\nПример: `(\"val_1\", \"val_2\", ..., \"val_N\"), (\"val_1\", \"val_2\", ..., \"val_N\"), ...`\n\n```php\n$db-\u003equery('INSERT INTO test (count, title, amount) VALUES ?v[?i, ?s, ?d]', [\n    [\n        [30.25, 'Какой-то заголовок', '66.55'],\n        [40, 'Какой-то заголовок 2', '77'],\n        ['21.55', 'Какой-то заголовок 3', 66.88]\n    ]\n]);\n```\nSQL-запрос после преобразования шаблона:\n```sql\nINSERT INTO test (count, title, amount) VALUES (30, 'Какой-то заголовок', 66.55), (40, 'Какой-то заголовок 2', 77), (21, 'Какой-то заголовок 3', 66.88)\n```\n\n### `?w*` — заполнитель ассоциативного множества из ассоциативного массива, генерирующий последовательность пар `ключ = значение` с разделителем `AND`\n Пример: `\"key_1\" = \"val_1\" AND \"key_2\" = \"val_2\" AND ... AND \"key_N\" = \"val_N\"`\n \n Ключи экранируются заполнителем `?f`\n \n где * после заполнителя — один из типов:\n * `i` (заполнитель целого числа)\n * `d` (заполнитель числа с плавающей точкой)\n * `s` (заполнитель строкового типа)\n * `f` (заполнитель имени таблицы или поля)\n \nПравила преобразования и экранирования такие же, как и для одиночных скалярных типов, описанных выше.\n \n```php\n$db-\u003equery('SELECT * FROM test WHERE ?wi', [\n    ['count' =\u003e 30, 'amount' =\u003e 1000, 'status' =\u003e 66]\n]);\n```\n  SQL-запрос после преобразования шаблона:\n```sql\nSELECT * FROM test WHERE `count` = 30 AND amount = 1000 AND status = 66\n```\n\n### `?w[?n, ?s, ?i, ?d, ...]` — заполнитель ассоциативного множества с явным указанием типа и количества аргументов, генерирующий последовательность пар `ключ = значение` с разделителем `AND`\n\nПример: `\"key_1\" = \"val_1\" AND \"key_2\" =\u003e \"val_2\" AND ... AND \"key_N\" = \"val_N\"`\n\n```php\n$db-\u003equery('SELECT * FROM test WHERE ?w[?i, ?s, ?d]', [\n    ['count' =\u003e 30.25, 'title' =\u003e 'Какой-то заголовок', 'amount' =\u003e '66.55']\n]);\n```\n  SQL-запрос после преобразования шаблона:\n```sql\nSELECT * FROM test WHERE `count` = 30 AND `title` = 'Какой-то заголовок' AND `amount` = 66.55\n```\n\n### Примеры для понимания сути заполнителей\n\n#### Различные варианты INSERT:\n\n##### Простая вставка данных через заполнители разных типов:\n\n```php\n$db-\u003equery(\"INSERT INTO `users` VALUES (?n, ?s, ?i, ?s)\", ['Иоанн Грозный', '54', 'в палатах']);\n```\n\nSQL-запрос после преобразования шаблона:\n\n```sql\nINSERT INTO `users` VALUES (NULL, 'Иоанн Грозный', 54, 'в палатах')\n```\n\n##### Вставка значений через заполнитель ассоциативного множества типа string:\n\n```php\n$user = ['name' =\u003e 'Пётр', 'age' =\u003e '30', 'adress' =\u003e \"ООО 'Рога и Копыта'\"];\n$db-\u003equery('INSERT INTO `users` SET ?As', [$user]);\n```\nSQL-запрос после преобразования шаблона:\n\n```sql\nINSERT INTO `users` SET `name` = \"Пётр\", `age` = \"30\", `adress` = \"ООО \\'Рога и Копыта\\'\"\n```\n\n##### Вставка значений через заполнитель ассоциативного множества с явным указанием типа и количества аргументов:\n```php\n$user = ['name' =\u003e \"Д'Артаньян\", 'age' =\u003e '19', 'adress' =\u003e 'замок Кастельмор'];\n$db-\u003equery('INSERT INTO `users` SET ?A[?s, ?i, ?s]', [$user]);\n```\nSQL-запрос после преобразования шаблона:\n\n```sql\nINSERT INTO `users` SET `name` = \"Д\\'Артаньян\",`age` = 19,`adress` = \"замок Кастельмор\"\n```\n\n#### Различные варианты SELECT\n\n##### Укажем некорректный числовой параметр - значение типа double:\n```php\n$db-\u003equery('SELECT * FROM `users` WHERE `id` = ?i', ['1.00']);\n```\nSQL-запрос после преобразования шаблона:\n\n```sql\nSELECT * FROM `users` WHERE `id` = 1\n```\n\n---\n\n```php  \n$db-\u003equery(\n    'SELECT id, adress FROM `users` WHERE `name` IN (?a[\"?s\", \"?s\", \"?s\"])',\n    [['Василий', 'Иван', \"Д'Артаньян\"]]\n); \n```\nSQL-запрос после преобразования шаблона:\n\n```sql\nSELECT id, adress FROM `users` WHERE `name` IN (\"Василий\", \"Иван\", \"Д\\'Артаньян\")\n```\n\n##### Имя базы данных, таблицы и поля передаются также, как и аргументы запроса\n```php  \n$db-\u003equery(\n    'SELECT * FROM ?f WHERE ?f IN (?as) OR `id` IN (?ai)',\n    'users', 'users.name', ['Василий'], ['2', 3.000]\n);\n```\nSQL-запрос после преобразования шаблона:\n\n```sql\nSELECT * FROM `users` WHERE `users`.`name` IN (\"Василий\") OR `id` IN (2, 3)\n```\n\n### Методы ORM\n\nВ библиотеке есть несколько методов ORM. Заполнители встроены дополнительным 2-ым параметром,\nостальные параметры методов сдвинуты. Методы с поддержкой заполнителей:\n * exec()\n * execCommit()\n * query()\n * prepare()\n \nПример:\n```php\n\u003c?php\nrequire_once \"vendor/autoload.php\"; //Подключаем библиотеку\nuse DigitalStars\\DataBase\\DB;\n\n$db = new DB('sqlite:./test.sqlite');\n// Вернёт PDOStatement\n$stm = $db-\u003eprepare(\"SELECT * FROM ?f WHERE name = ?s AND count = ?\", ['test', 'имя']);\n\n// Вернёт выборку где count = 100\nif ($stm-\u003eexecute([100]))\n    print_r($stm-\u003efetchAll());\n\n// Вернёт выборку где count = 200\nif ($stm-\u003eexecute([200]))\n    print_r($stm-\u003efetchAll());\n```\n\n## Дополнительные методы\n### getQueryString() : sql (string)\n\nМетод возвращает последний собранный запрос, в котором были заполнители\n```php\n$stm = $db-\u003eprepare(\"SELECT * FROM ?f WHERE name = ?s AND count = ?\", ['test', 'имя']);\n\necho $db-\u003egetQueryString();\n```\n\nВернёт\n\n```sql\nSELECT * FROM `test` WHERE name = 'имя' AND count = ?\n```\n\n### execCommit() : int | false\n\nАналогичен `exec()`, но запрос проходит с использованием `beginTransaction()`, `commit()` и `rollBack()` в случае неудачи.\n\n```php\n$db-\u003eexecCommit(\"DELETE FROM users WHERE id = ?i\", [5]);;\n```\n\n### rows($sql, $args = [], $fetchMode = PDO::FETCH_ASSOC) : array | false\n\nСоберёт `$sql` запрос по заполнителям из `$args` и вернёт все строки (вызов `PDOStatement::fetchAll`) с режимом выборки `$fetchMode`.  \n\u003e Подробнее о режимах выборки [PHP-PDO](https://www.php.net/manual/ru/book.pdo.php)\n\n```php\n$rows = $db-\u003erows(\"SELECT * FROM users WHERE age = ?i\", [30]);\n// Вернёт false или все строки таблицы, где age = 30\n```\n\n### row($sql, $args = [], $fetchMode = PDO::FETCH_ASSOC) : array | false\n\nСоберёт `$sql` запрос по заполнителям из `$args` и вернёт строку (вызов `PDOStatement::fetch`) с режимом выборки `$fetchMode`.  \n\u003eПодробнее о режимах выборки [PHP-PDO](https://www.php.net/manual/ru/book.pdo.php)\n\n```php\n$row = $db-\u003erow(\"SELECT * FROM users WHERE age = ?i\", [30]);\n// Вернёт false или строку таблицы, где age = 30\n```\n\n### getById($table, $id, $fetchMode = PDO::FETCH_ASSOC) : array | false\n\nВернёт строку (вызов `PDOStatement::fetch`) с режимом выборки `$fetchMode` из таблицы `$table` ро правилу, описанному ниже.  \n\u003eПодробнее о режимах выборки [PHP-PDO](https://www.php.net/manual/ru/book.pdo.php)\n\n* Если `$id` - число, то вернёт запись, где `id = $id`\n\n* Если `$id` - массив, то вернёт запись по WHERE, где ключи массив - названия полей, значения массива - значения полей\n\n```php\n$row = $db-\u003egetById('users', 6);\n// Выполнит SELECT * FROM `users` WHERE id = 6\n// Вернёт false или строку таблицы, где id = 6\n\n$row = $db-\u003egetById('users', ['user_id' =\u003e 12, 'status' =\u003e 5]);\n// Выполнит SELECT * FROM `users` WHERE user_id = '12' AND status = '5'\n// Вернёт false или строку таблицы, где user_id = 12 или status = 5\n```\n\n### count($sql, $args = []) : int | false\n\nСоберёт `$sql` запрос по заполнителям из `$args` и вернёт количество затронутых строк (вызов метода `PDOStatement::rowCount`)\n\n```php\n$row = $db-\u003ecount('SELECT * FROM users WHERE name = ?s', ['Василий']);\n// Вернёт false или количество строк таблицы users, в которых name = 'Василий'\n```\n\n### insert($table, $data) : int | false\n\nВставит в таблицу `$table` значения из массива `$data`, в котором ключи - названия полей, значения - значения полей. Вернёт `id` добавленной записи\n\n```php\n$last_id = $db-\u003einsert('users', ['name' =\u003e 'Иван', 'age' =\u003e 30]);\n// Выполнит запрос: INSERT INTO `users` (`name`, `age`) VALUES ('Иван', '30')\n// Вернёт false или ID добавленной записи\n```\n\n### update($table, $data, $where = []) : int | false\n\nИзменить таблицу `$table` значениями из массива `$data`, в котором ключи - названия полей,\nзначения - значения полей, где по `$where`, в котором ключи - названия полей,\nзначения - значения полей. Вернёт количество затронутых строк или `false` в случае ошибки.\n\n\u003e **Внимание!** Если функция отработала без ошибок, но затронула `0 строк` - она вернёт `0`. Что при нестрогой проверке приведётся к `false`\n\n\u003e Если не передан `$where`, то будут затронуты все строки\n\n```php\n$count = $db-\u003eupdate('users', \n    [\n        'name' =\u003e 'Иван',\n        'age' =\u003e 30\n    ],\n    [\n        'id' =\u003e 6,\n        'status' =\u003e 9\n    ]);\n// Выполнит запрос: UPDATE `users` SET `name` = 'Иван', `age` = '30' WHERE `id` = '6' AND `status` = '9'\n// Вернёт false или количество затронутых строк\n```\n\n### delete($table, $where, $limit = -1) : int | false\n\nУдалить из таблицы `$table` `$limit` записей, где по `$where`, в котором ключи - названия полей,\nзначения - значения полей. Вернёт количество затронутых строк или `false` в случае ошибки.\n\n\u003e **Внимание!** Если функция отработала без ошибок, но затронула `0 строк` - она вернёт `0`. Что при нестрогой проверке приведётся к `false`\n\n\u003e Если не передан `$limit` или равен `-1`, то будут удален все выбранные записи\n\n```php\n$count = $db-\u003edelete('users', ['id' =\u003e 6, 'status' =\u003e 9], 5);\n// Выполнит запрос: DELETE FROM `users` WHERE `id` = '6' AND `status` = '9' LIMIT 5\n// Вернёт false или количество затронутых строк\n```\n\n### deleteAll($table) : int | false\n\nУдалить из таблицы `$table` все записи. Вернёт количество затронутых строк или `false` в случае ошибки.\n\n\u003e **Внимание!** Если функция отработала без ошибок, но затронула `0 строк` - она вернёт `0`. Что при нестрогой проверке приведётся к `false`\n\n```php\n$count = $db-\u003edeleteAll('users');\n// Выполнит запрос: DELETE FROM `users`\n// Вернёт false или количество затронутых строк\n```\n\n### deleteById($table, $id) : int | false\n\nУдалить из таблицы `$table` записи с `id = $id`. Вернёт количество затронутых строк или `false` в случае ошибки.\n\n\u003e **Внимание!** Если функция отработала без ошибок, но затронула `0 строк` - она вернёт `0`. Что при нестрогой проверке приведётся к `false`\n\n```php\n$count = $db-\u003edeleteById('users', 6);\n// Выполнит запрос: DELETE FROM `users` WHERE `id` = 6\n// Вернёт false или количество затронутых строк\n```\n\n### deleteByIds($table, $column, $ids) : int | false\n\nУдалить из таблицы `$table` записи, где `$column` равен одному из `$ids`. Вернёт количество затронутых строк или `false` в случае ошибки.\n\n\u003e `$ids` должен быть обычным или ассоциативным массивом.\n\n\u003e **Внимание!** Если функция отработала без ошибок, но затронула `0 строк` - она вернёт `0`. Что при нестрогой проверке приведётся к `false`\n\n```php\n$count = $db-\u003edeleteByIds('users', 'status', [6, 8, 10]);\n// Выполнит запрос: DELETE FROM `users` WHERE `status` IN ('6', '8', '10')\n// Вернёт false или количество затронутых строк\n```\n\n### truncate($table) : int | false\n\nОчищает таблицу `$table`. Вернёт количество затронутых строк или `false` в случае ошибки.\n\n\u003e Сбрасываются также внутренние счётчики таблицы\n\n\u003e **Внимание!** Если функция отработала без ошибок, но затронула `0 строк` - она вернёт `0`. Что при нестрогой проверке приведётся к `false`\n\n```php\n$count = $db-\u003etruncate('users');\n// Выполнит запрос: TRUNCATE TABLE `users`\n// Вернёт false или количество затронутых строк\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigitalstars%2Fdatabase","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdigitalstars%2Fdatabase","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigitalstars%2Fdatabase/lists"}