Download the PHP package digitalstars/database without Composer

Комьюнити:

Почему DataBase?

• Универсальность — Благодаря тому, что DataBase наследуется от PHP-PDO, её можно использовать с различными БД.
• Простота — DataBase включает в себя удобные заполнители, которы серьёзно упрощают работу с SQL запросами. Также частые SQL запросы уже составлены и вынесены в виде методов.
• При использовании Заполнителей, вы полностью защищены от SQL инъекций.

  Функционал

  В библиотеке поддерживается:

  • Все методы PHP-PDO
  • Свои заполнители
  • ORM конструкции

Оглавление

• Подключение
• Заполнители
• Настройка PhpStorm
• Хандлер sql запросов
• Типы заполнителей
  • ?i (int)
  • ?d (double)
  • ?s (string)
  • ?S (string) (для LIKE)
  • ?n (null)
  • ?f (field)
  • ?A* (ассоциативный массив)
  • ?A[?n, ?s, ?i, ?d, ...] (ассоциативный массив)
  • ?a* (массив)
  • ?a[?n, ?s, ?i, ?d, ...] (массив)
  • ?v* (VALUES)
  • ?v[?n, ?s, ?i, ?d, ...] (VALUES)
  • ?w* (WHERE)
  • ?w[?n, ?s, ?i, ?d, ...] (WHERE)
• Дополнительные методы
  • getQueryString
  • execCommit
  • rows($sql, $args = [], $fetchMode = PDO::FETCH_ASSOC)
  • row($sql, $args = [], $fetchMode = PDO::FETCH_ASSOC)
  • getById($table, $id, $fetchMode = PDO::FETCH_ASSOC)
  • count($sql, $args = [])
  • insert($table, $data)
  • update($table, $data, $where = [])
  • delete($table, $where, $limit = -1)
  • deleteAll($table)
  • deleteById($table, $id)
  • deleteByIds($table, $column, $ids)
  • truncate($table)

Подключение

Используя composer

Вручную

1. Скачать последний релиз
2. Подключить autoload.php

   Вот так будет происходить подключение, если ваш бот находится в той же папке, что и папка DataBase-master

Подключение к СуБД

Синтаксис конструктора базового класса такой же, как и у PHP-PDO

Пример подключения к MySQL

Пример подключение к SQLite

Что такое заполнители?

Заполнители — специальные типизированные маркеры, которые пишутся в строке SQL запроса вместо явных значений (параметров запроса), чем упрощают читаемость кода и защищают от SQL инъекций.
Заполнители поддерживаются в следующих методах:

• exec()
• execCommit()
• query()
• prepare()

  О том как работают эти методы можно посмотреть в PHP-PDO.

Параметры SQL-запроса, прошедшие через заполнители, обрабатываются специальными функциями экранирования, в зависимости от типа заполнителей. Т.е. вам теперь нет необходимости заключать переменные в функции экранирования типа quote() или приводить их к числовому типу, как это было раньше

Типы заполнителей и типы параметров SQL-запроса

Типы заполнителей и их предназначение описываются ниже. Прежде чем знакомиться с типами заполнителей, необходимо понять как работает механизм библиотеки DataBase.

SQL-запрос после преобразования шаблона:

В процессе исполнения этой команды библиотека проверяет, является ли аргумент 123 целочисленным значением. Заполнитель ?i представляет собой символ ? (знак вопроса) и первую букву слова integer. Если аргумент действительно представляет собой целочисленный тип данных, то в шаблоне SQL-запроса заполнитель ?i заменяется на значение 123 и SQL передается на исполнение.

Поскольку PHP слаботипизированный язык, то вышеописанное выражение эквивалентно нижеописанному:

SQL-запрос после преобразования шаблона:

Т.е. числа (целые и с плавающей точкой) представленные как в своем типе, так и в виде string — равнозначны с точки зрения библиотеки.

Приведение к типу заполнителя

SQL-запрос после преобразования шаблона:

В данном примере заполнитель целочисленного типа данных ожидает значение типа integer, а передается double.

Допускаются следующие преобразования:

• К типу int (заполнитель ?i) приводятся:
  • Числа с плавающей точкой, представленные как string или double
  • bool(true) преобразуется в int(1)
  • bool(false) и null преобразуется в int(0)
• К типу double (заполнитель ?d) приводятся:
  • Целые числа, представленные как string или int
  • bool(true) преобразуется в float(1)
  • bool(false) и null преобразуется в float(0)
• К типу string (заполнитель ?s) приводятся:
  • numeric преобразуется в string
  • null преобразуется в string(0) ""
  • bool(true) преобразуется в string(1) "1"
  • bool(false) преобразуется в string(1) "0"

    Это поведение отличается от приведения типа bool к int в PHP, т.к. зачастую на практике bool записывается в MySql именно как число.

• Тип null (заполнитель ?n) просто вставляет NULL в место заполнителя.
  Входные параметры не требуются

Настройка PhpStorm

Для того, что-бы IDE нормально реагировала на заполнители, и не подсвечивала места с заполнителями ошибками, необходимо добавить заполнители в список пользовательских параметров.

Путь диалогового окна с настройками

File >> Settings... >> Tools >> Database >> User Parameters

Затем в окошке "Parameter patterns" нужно добавить следующие 2 шаблона и поставить обе галочки "In scripts" и "In literals":

• \?[aAvw]\[.*?\]
• \?[aAvw]?[sSidnf]

Окно настройки должно выглядеть следующим образом

Хандлер sql запросов

Если вам необходимо обрабатывать все выполняемые в скрипте SQL запросы, например для дебага.

Типы заполнителей DataBase

?i — заполнитель целого числа

SQL-запрос после преобразования шаблона:

ВНИМАНИЕ! Если вы оперируете числами, выходящими за пределы PHP_INT_MAX, то:

• Оперируйте ими исключительно как строками в своих программах.
• Не используйте данный заполнитель, используйте заполнитель строки ?s (см. ниже). Дело в том, что числа, выходящие за пределы PHP_INT_MAX, PHP интерпретирует как числа с плавающей точкой. Парсер библиотеки постарается преобразовать параметр к типу int, в итоге:

  «результат будет неопределенным, так как float не имеет достаточной точности, чтобы вернуть верный результат. В этом случае не будет выведено ни предупреждения, ни даже замечания!» — php.net.

?d — заполнитель числа с плавающей точкой

ВНИМАНИЕ! Если вы используете библиотеку для работы с типом данных double, установите соответствующую локаль, что бы разделитель целой и дробной части был одинаков как на уровне PHP, так и на уровне СУБД.

?s — заполнитель строкового типа

Значения экранируются с помощью функции PDO::quote()

SQL-запрос после преобразования шаблона:

?S — заполнитель строкового типа для подстановки в SQL-оператор LIKE

Значения экранируются с помощью функции PDO::quote() + экранирование спецсимволов, используемых в операторе LIKE (% и _):

SQL-запрос после преобразования шаблона:

?n — заполнитель NULL типа

Заполнитель просто вставляет NULL в запрос, входной параметр не нужен

SQL-запрос после преобразования шаблона:

?f — заполнитель имени таблицы или поля

Данный заполнитель предназначен для случаев, когда имя таблицы или поля передается в запросе через параметр. Значение обрамляется символом апостроф:

SQL-запрос после преобразования шаблона:

?A* — заполнитель ассоциативного множества из ассоциативного массива, генерирующий последовательность пар ключ = значение

Пример: "key_1" = "val_1", "key_2" = "val_2", ..., "key_N" = "val_N"
Ключи экранируются заполнителем ?f

где * после заполнителя — один из типов:

• i (заполнитель целого числа)
• d (заполнитель числа с плавающей точкой)
• s (заполнитель строкового типа)
• f (заполнитель имени таблицы или поля)

Правила преобразования и экранирования такие же, как и для одиночных скалярных типов, описанных выше.

SQL-запрос после преобразования шаблона:

?A[?n, ?s, ?i, ?d, ...] — заполнитель ассоциативного множества с явным указанием типа и количества аргументов, генерирующий последовательность пар ключ = значение

Пример: "key_1" = "val_1", "key_2" => "val_2", ..., "key_N" = "val_N"

SQL-запрос после преобразования шаблона:

?a* — заполнитель множества из простого (или также ассоциативного) массива, генерирующий последовательность значений

Пример: "val_1", "val_2", ..., "val_N"

где * после заполнителя — один из типов:

• i (заполнитель целого числа)
• d (заполнитель числа с плавающей точкой)
• s (заполнитель строкового типа)

• f (заполнитель имени таблицы или поля)

  правила преобразования и экранирования такие же, как и для одиночных скалярных типов, описанных выше.

  SQL-запрос после преобразования шаблона:

?a[?n, ?s, ?i, ?d, ...] — заполнитель множества с явным указанием типа и количества аргументов, генерирующий последовательность значений

Пример: "val_1", "val_2", ..., "val_N"

SQL-запрос после преобразования шаблона:

?v* — заполнитель VALUES из простого (или также ассоциативного) двумерного массива, генерирующий последовательность значений для заполнения VALUES

Пример: ("val_1", "val_2", ..., "val_N"), ("val_1", "val_2", ..., "val_N"), ...

где * после заполнителя — один из типов:

• i (заполнитель целого числа)
• d (заполнитель числа с плавающей точкой)
• s (заполнитель строкового типа)

• f (заполнитель имени таблицы или поля)

  правила преобразования и экранирования такие же, как и для одиночных скалярных типов, описанных выше.

  SQL-запрос после преобразования шаблона:

?v[?n, ?s, ?i, ?d, ...] — заполнитель множества из двумерного массива с явным указанием типа и количества аргументов, генерирующий последовательность значений для заполнения VALUES

Пример: ("val_1", "val_2", ..., "val_N"), ("val_1", "val_2", ..., "val_N"), ...

SQL-запрос после преобразования шаблона:

?w* — заполнитель ассоциативного множества из ассоциативного массива, генерирующий последовательность пар ключ = значение с разделителем AND

Пример: "key_1" = "val_1" AND "key_2" = "val_2" AND ... AND "key_N" = "val_N"

Ключи экранируются заполнителем ?f

где * после заполнителя — один из типов:

• i (заполнитель целого числа)
• d (заполнитель числа с плавающей точкой)
• s (заполнитель строкового типа)
• f (заполнитель имени таблицы или поля)

Правила преобразования и экранирования такие же, как и для одиночных скалярных типов, описанных выше.

SQL-запрос после преобразования шаблона:

?w[?n, ?s, ?i, ?d, ...] — заполнитель ассоциативного множества с явным указанием типа и количества аргументов, генерирующий последовательность пар ключ = значение с разделителем AND

Пример: "key_1" = "val_1" AND "key_2" => "val_2" AND ... AND "key_N" = "val_N"

SQL-запрос после преобразования шаблона:

Примеры для понимания сути заполнителей

Различные варианты INSERT:

Простая вставка данных через заполнители разных типов:

SQL-запрос после преобразования шаблона:

Вставка значений через заполнитель ассоциативного множества типа string:

SQL-запрос после преобразования шаблона:

Вставка значений через заполнитель ассоциативного множества с явным указанием типа и количества аргументов:

SQL-запрос после преобразования шаблона:

Различные варианты SELECT

Укажем некорректный числовой параметр - значение типа double:

SQL-запрос после преобразования шаблона:

SQL-запрос после преобразования шаблона:

Имя базы данных, таблицы и поля передаются также, как и аргументы запроса

SQL-запрос после преобразования шаблона:

Методы ORM

В библиотеке есть несколько методов ORM. Заполнители встроены дополнительным 2-ым параметром, остальные параметры методов сдвинуты. Методы с поддержкой заполнителей:

• exec()
• execCommit()
• query()
• prepare()

Пример:

Дополнительные методы

getQueryString() : sql (string)

Метод возвращает последний собранный запрос, в котором были заполнители

Вернёт

execCommit() : int | false

Аналогичен exec(), но запрос проходит с использованием beginTransaction(), commit() и rollBack() в случае неудачи.

rows($sql, $args = [], $fetchMode = PDO::FETCH_ASSOC) : array | false

Соберёт $sql запрос по заполнителям из $args и вернёт все строки (вызов PDOStatement::fetchAll) с режимом выборки $fetchMode.

Подробнее о режимах выборки PHP-PDO

row($sql, $args = [], $fetchMode = PDO::FETCH_ASSOC) : array | false

Соберёт $sql запрос по заполнителям из $args и вернёт строку (вызов PDOStatement::fetch) с режимом выборки $fetchMode.

Подробнее о режимах выборки PHP-PDO

getById($table, $id, $fetchMode = PDO::FETCH_ASSOC) : array | false

Вернёт строку (вызов PDOStatement::fetch) с режимом выборки $fetchMode из таблицы $table ро правилу, описанному ниже.

Подробнее о режимах выборки PHP-PDO

• Если $id - число, то вернёт запись, где id = $id

• Если $id - массив, то вернёт запись по WHERE, где ключи массив - названия полей, значения массива - значения полей

count($sql, $args = []) : int | false

Соберёт $sql запрос по заполнителям из $args и вернёт количество затронутых строк (вызов метода PDOStatement::rowCount)

insert($table, $data) : int | false

Вставит в таблицу $table значения из массива $data, в котором ключи - названия полей, значения - значения полей. Вернёт id добавленной записи

update($table, $data, $where = []) : int | false

Изменить таблицу $table значениями из массива $data, в котором ключи - названия полей, значения - значения полей, где по $where, в котором ключи - названия полей, значения - значения полей. Вернёт количество затронутых строк или false в случае ошибки.

Внимание! Если функция отработала без ошибок, но затронула 0 строк - она вернёт 0. Что при нестрогой проверке приведётся к false

Если не передан $where, то будут затронуты все строки

delete($table, $where, $limit = -1) : int | false

Удалить из таблицы $table $limit записей, где по $where, в котором ключи - названия полей, значения - значения полей. Вернёт количество затронутых строк или false в случае ошибки.

Внимание! Если функция отработала без ошибок, но затронула 0 строк - она вернёт 0. Что при нестрогой проверке приведётся к false

Если не передан $limit или равен -1, то будут удален все выбранные записи

deleteAll($table) : int | false

Удалить из таблицы $table все записи. Вернёт количество затронутых строк или false в случае ошибки.

Внимание! Если функция отработала без ошибок, но затронула 0 строк - она вернёт 0. Что при нестрогой проверке приведётся к false

deleteById($table, $id) : int | false

Удалить из таблицы $table записи с id = $id. Вернёт количество затронутых строк или false в случае ошибки.

Внимание! Если функция отработала без ошибок, но затронула 0 строк - она вернёт 0. Что при нестрогой проверке приведётся к false

deleteByIds($table, $column, $ids) : int | false

Удалить из таблицы $table записи, где $column равен одному из $ids. Вернёт количество затронутых строк или false в случае ошибки.

$ids должен быть обычным или ассоциативным массивом.

Внимание! Если функция отработала без ошибок, но затронула 0 строк - она вернёт 0. Что при нестрогой проверке приведётся к false

truncate($table) : int | false

Очищает таблицу $table. Вернёт количество затронутых строк или false в случае ошибки.

Сбрасываются также внутренние счётчики таблицы

Внимание! Если функция отработала без ошибок, но затронула 0 строк - она вернёт 0. Что при нестрогой проверке приведётся к false