Download the PHP package krugozor-old/database without Composer

Получение библиотеки

Вы можете скачать её архивом, клонировать с данного сайта или загрузить через composer (ссылка на packagist.org):

composer require krugozor/database

Изменения

v2.0 - 25.02.2021

• Поддержка sleep/wakeup
• Изменены названия методов в классе Statement (старые методы назывались не в CamelCase стиле по историческим причинам)
• Изменено пространство имён

v1.0

• Больше не поддерживается, советую переходить на релиз v2.0

Что такое Database?

Database — библиотека классов на PHP >= 5.3 для простой, удобной, быстрой и безопасной работы с базой данных MySql, использующая расширение PHP mysqli.

Зачем нужен самописный класс для MySql, если в PHP есть абстракция PDO и расширение mysqli?

Основные недостатки всех библиотек для работы с базой в PHP это:

• Многословность
  • Что бы предотвратить SQL-инъекции, у разработчиков есть два пути:
  • Использовать подготавливаемые запросы (prepared statements).
  • Вручную экранировать параметры идущие в тело SQL-запроса. Строковые параметры прогонять через mysqli_real_escape_string(), а ожидаемые числовые параметры приводить к соответствующим типам — int и float.
  • Оба подхода имеют колоссальные недостатки:
  • Подготавливаемые запросы ужасно многословны. Пользоваться "из коробки" абстракцией PDO или расширением mysqli, без агрегирования всех методов для получения данных из СУБД просто невозможно — что бы получить значение из таблицы необходимо написать минимум 5 строк кода! И так на каждый запрос!
  • Экранирование вручную параметров, идущих в тело SQL-запроса — даже не обсуждается. Хороший программист — ленивый программист. Всё должно быть максимально автоматизировано.
• Невозможность получить SQL запрос для отладки
  • Что бы понять, почему в программе не работает SQL-запрос, его нужно отладить — найти либо логическую, либо синтаксическую ошибку. Что бы найти ошибку, необходимо "видеть" сам SQL-запрос, на который "ругнулась" база, с подставленными в его тело параметрами. Т.е. иметь сформированный полноценный SQL. Если разработчик использует PDO, с подготавливаемыми запросами, то это сделать... НЕВОЗМОЖНО! Никаких максимально удобных механизмов для этого в родных библиотеках НЕ ПРЕДУСМОТРЕНО. Остается либо извращаться, либо лезть в лог базы данных.

Решение: Database — класс для работы с MySql

1. Избавляет от многословности — вместо 3 и более строк кода для исполнения одного запроса при использовании "родной" библиотеки, вы пишите всего 1.
2. Экранирует все параметры, идущие в тело запроса, согласно указанному типу заполнителей — надежная защита от SQL-инъекций.
3. Не замещает функциональность "родного" mysqli адаптера, а просто дополняет его.

Чем НЕ является библиотека Database?

Большинство оберток под различные драйверы баз данных являются нагромождением бесполезного кода с отвратительной архитектурой. Их авторы, сами не понимая практической цели своих оберток, превращают их в подобие построителей запросов (sql builder), ActiveRecord библиотек и прочих ORM-решений.

Библиотека Database не является ничем из перечисленных. Это лишь удобный инструмент для работы с обычным SQL в рамках СУБД MySQL — и не более!

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

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

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

Теперь запросы стало писать легко, быстро, а главное библиотека Database полностью предотвращает любые возможные SQL-инъекции.

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

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

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

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

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

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

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

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

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

В данном примере заполнитель целочисленного типа данных ожидает значение типа integer, а передается double. По-умолчанию библиотека работает в режиме приведения типов, что дало в итоге приведение типа double к int.

Режимы работы библиотеки и принудительное приведение типов

Существует два режима работы библиотеки:

• Mysql::MODE_STRICT — строгий режим соответствия типа заполнителя и типа аргумента. В режиме MODE_STRICT аргументы должны соответствовать типу заполнителя. Например, попытка передать в качестве аргумента значение 55.5 или '55.5' для заполнителя целочисленного типа ?i приведет к выбросу исключения:

• Mysql::MODE_TRANSFORM — режим преобразования аргумента к типу заполнителя при несовпадении типа заполнителя и типа аргумента. Режим MODE_TRANSFORM установлен по-умолчанию и является "толерантным" режимом — при несоответствии типа заполнителя и типа аргумента не генерирует исключение, а пытается преобразовать аргумент к нужному типу заполнителя посредством самого языка PHP. К слову сказать, я, как автор библиотеки, всегда использую именно этот режим, строгий режим (Mysql::MODE_STRICT) я сделал чисто "по фану" и в реальной работе никогда не использовал.

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

• К типу int (заполнитель ?i) приводятся
  • числа с плавающей точкой, представленные как string или тип double
  • bool TRUE преобразуется в int(1), FALSE преобразуется в int(0)
  • null преобразуется в int(0)
• К типу double (заполнитель ?d) приводятся
  • целые числа, представленные как string или тип int
  • bool TRUE преобразуется в float(1), FALSE преобразуется в float(0)
  • null преобразуется в float(0)
• К типу string (заполнитель ?s) приводятся
  • bool TRUE преобразуется в string(1) "1", FALSE преобразуется в string(1) "0". Это поведение отличается от приведения типа bool к int в PHP, т.к. зачастую, на практике, булев тип записывается в MySql именно как число.
  • значение типа numeric преобразуется в строку согласно правилам преобразования PHP
  • NULL преобразуется в string(0) ""
• К типу null (заполнитель ?n) приводятся
  • любые аргументы.
• Для массивов, объектов и ресурсов преобразования не допускаются.

Какие типы заполнителей представлены в библиотеке Database?

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

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

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

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

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

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

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

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

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

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

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

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

Значение любых аргументов игнорируются, заполнители заменяются на строку NULL в SQL запросе:

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

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

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

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

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

• s (заполнитель строкового типа)

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

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

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

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

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

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

• s (заполнитель строкового типа)

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

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

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

Пример:

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

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

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

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

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

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

Ограничивающие кавычки

Библиотека требует от программиста соблюдения синтаксиса SQL. Это значит, что следующий запрос работать не будет:

— заполнитель ?s необходимо взять в одинарные или двойные кавычки:

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

Для тех, кто привык работать с PDO это покажется странным, но реализовать механизм, определяющий, нужно ли в одном случае заключать значение заполнителя в кавычки или нет — очень нетривиальная задача, трубующая написания целого парсера.

Примеры работы с библиотекой

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

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

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

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

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

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

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

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

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

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

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

---

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

Имя базы данных, таблицы и поля передаются также, как и аргументы запроса. Не удивляйтесь имени поля '.users.name' - это допустимый для MySql синтаксис:

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

Некоторые возможности API

Применение метода queryArguments() - аргументы передаются в виде массива. Это второй, после метода query(), метод запросов в базу:

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

Получить все в виде ассоциативных массивов:

Получить одно значение из выборки:

Получить все SQL-запросы текущего соединения: