babaev-an/php_db_components_pack
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity
php_db_components_pack/help/class_desc/classes/ConditionBuilder.md
babaev-an d132832d28 20250807
2025-08-07 18:06:55 +03:00

12 KiB
Raw Blame History

Класс ConditionBuilder

Класс ConditionBuilder предназначен для удобного построения сложных условий запросов к базе данных. Он позволяет постепенно наращивать цепь условий, используя цепочечные методы и логические операторы (AND, OR, NOT и т.д.), что значительно упрощает формирование SQL-запросов.

Пространство имён

namespace goodboyalex\php_db_components_pack\classes;

Автор и версия

  • Автор: Александр Бабаев
  • Версия: 1.0
  • Дата начала поддержки: с версии 1.0

Назначение

Класс ConditionBuilder позволяет гибко составлять сложные условия запросов к базе данных, последовательно добавляя условия и логические операторы. Это незаменимый инструмент для быстрого и простого создания запросов, основанных на многомерных фильтрах.

Основные элементы класса

Составляющие части

  • Логические операторы: Предусмотрены основные логические операторы (AND, OR, NOT, XOR, NAND, NOR), позволяющие объединять условия с необходимой логической связью.
  • Группа условий: Условия могут быть объединены в группы, что позволяет выстраивать сложную иерархию условий.
  • Защита от SQL-инъекций: Встроенная защита от SQL-инъекций обеспечивается за счёт возврата готовых параметров запроса.

Методы

1. Конструктор (__construct)

Назначение: Создаёт пустой объект, который впоследствии наполняется условиями.

Синтаксис:

public function __construct ();

Описание: Создаёт новый экземпляр класса ConditionBuilder, который далее будет использован для накопления условий и объединения их логическими операторами.

2. Метод Parse

Назначение: Прочитать и разобрать массив условий, созданный вручную или динамически, и создать объект для дальнейшей работы.

Синтаксис:

public static function Parse(array $conditions): ConditionBuilder;

Описание:

  • Метод принимает массив условий и логических операторов.
  • Каждое условие представляется элемент ассоциативного массива, ключом которого является имя столбца, а значение представляет собой массив из (1) оператора и (2) значения.
  • В роли массива значений может выступать и просто значение, тогда за оператор берётся оператор =.
  • Логические операторы (AND, OR, ...) могут находиться между условиями.
  • Пример входящего массива:
["id" => 1, 'AND', "age" => ['>=', 18], 'OR', "profile" => ['<=', 12]]
  • Результатом работы метода является объект ConditionBuilder, содержащий всю необходимую информацию для формирования SQL-запроса.

3. Метод AddGroup

Назначение: Добавляет группу условий, объединённых общим логическим оператором.

Синтаксис:

public function AddGroup(string $logicalOperator, array $conditions): ConditionBuilder;

Описание:

  • $logicalOperator: Логический оператор (AND, OR, и т.д.), который связывает условия в группе.
  • $conditions: Массив условий, относящихся к группе.
  • Метод добавляет группу условий и возвращает тот же объект ConditionBuilder, позволяя продолжить сборку цепочкой методов.

4. Метод Build

Назначение: Формирует финальную строку SQL-запроса и массив параметров для защиты от SQL-инъекций.

Синтаксис:

public function Build(): Tuple;

Описание:

  • Метод возвращает кортеж (Tuple), состоящий из двух элементов:
    • SQL-строка с условием, готовым к выполнению.
    • Массив параметров, необходимых для последующей передачи в подготовленный SQL-запрос.
  • Позволяет легко интегрировать построенное условие в SQL-запрос.

5. Метод Count

Назначение: Возвращает количество накопленных условий.

Синтаксис:

public function Count(): int;

Описание: Метод возвращает целое число, показывающее, сколько условий было собрано на текущий момент.

6. Метод WhereEquals

Назначение: Добавляет условие "равно".

Синтаксис:

public function WhereEquals(string $column, mixed $value): ConditionBuilder;

Описание:

  • $column: Имя колонки.
  • $value: Значение, с которым колонка сравнивается.
  • Метод добавляет условие в виде WHERE column = value и возвращает объект для продолжения цепочки.

7. Метод WhereNotEquals

Назначение: Добавляет условие "не равно".

Синтаксис:

public function WhereNotEquals(string $column, mixed $value): ConditionBuilder;

Описание:

  • Аналогичен предыдущему методу, но добавляет условие вида WHERE column <> value.

8. Метод WhereGreaterThan

Назначение: Добавляет условие "больше".

Синтаксис:

public function WhereGreaterThan(string $column, mixed $value): ConditionBuilder;

Описание:

  • Добавляет условие вида WHERE column > value.

9. Метод WhereLessThan

Назначение: Добавляет условие "меньше".

Синтаксис:

public function WhereLessThan(string $column, mixed $value): ConditionBuilder;

Описание:

  • Добавляет условие вида WHERE column < value.

10. Метод WhereGreaterThanEqual

Назначение: Добавляет условие "больше или равно".

Синтаксис:

public function WhereGreaterThanEqual(string $column, mixed $value): ConditionBuilder;

Описание:

  • Добавляет условие вида WHERE column >= value.

11. Метод WhereLessThanEqual

Назначение: Добавляет условие "меньше или равно".

Синтаксис:

public function WhereLessThanEqual(string $column, mixed $value): ConditionBuilder;

Описание:

  • Добавляет условие вида WHERE column <= value.

12. Метод AddLogicalOperator

Назначение: Добавляет логический оператор в цепочку условий.

Синтаксис:

public function AddLogicalOperator(string $operator): false|ConditionBuilder;

Описание:

  • $operator: Логический оператор (AND, OR, NOT, XOR, NAND, NOR).
  • Метод добавляет указанный оператор в последовательность условий и возвращает объект для продолжения цепочки. Если оператор неправильный, возвращает false.

13. Метод And

Назначение: Добавляет логический оператор AND.

Синтаксис:

public function And(): ConditionBuilder;

Описание: Удобный аналог метода AddLogicalOperator, предназначенный специально для оператора AND.

14. Метод Or

Назначение: Добавляет логический оператор OR.

Синтаксис:

public function Or(): ConditionBuilder;

Описание: Удобный аналог метода AddLogicalOperator, предназначенный специально для оператора OR.

15. Метод Not

Назначение: Добавляет логический оператор NOT.

Синтаксис:

public function Not(): ConditionBuilder;

Описание: Удобный аналог метода AddLogicalOperator, предназначенный специально для оператора NOT.

16. Метод Xor

Назначение: Добавляет логический оператор XOR.

Синтаксис:

public function Xor(): ConditionBuilder;

Описание: Удобный аналог метода AddLogicalOperator, предназначенный специально для оператора XOR.

17. Метод Nand

Назначение: Добавляет логический оператор NAND.

Синтаксис:

public function Nand(): ConditionBuilder;

Описание: Удобный аналог метода AddLogicalOperator, предназначенный специально для оператора NAND.

18. Метод Nor

Назначение: Добавляет логический оператор NOR.

Синтаксис:

public function Nor(): ConditionBuilder;

Описание: Удобный аналог метода AddLogicalOperator, предназначенный специально для оператора NOR.

Пример использования

Допустим, у вас есть задача отобрать пользователей, чей возраст превышает 18 лет и они зарегистрированы позже определённой даты:

use goodboyalex\php_db_components_pack\classes\ConditionBuilder;

// Создаём объект ConditionBuilder
$builder = new ConditionBuilder()->WhereGreaterThan('age', 18)->And()->WhereGreaterThan('registration_date', '2023-01-01');

// Собираем условия
[$sqlFragment, $params] = $builder->Build();

В результате можно будет создать такой запрос:

SELECT *
FROM `TABLE`
WHERE (`age` > 18)
  AND (`registration_date` > '2023-01-01');

Принцип работы

Класс ConditionBuilder постепенно аккумулирует условия, создавая дерево зависимостей, состоящее из условий и логических операторов. За счёт этого появляется возможность легко создавать и редактировать сложные фильтры для запросов к базе данных.

На главную