20250807

2025-08-07 18:06:55 +03:00
parent eeea57209e
commit d132832d28
34 changed files with 1231 additions and 286 deletions
--- a/help/class_desc/classes/ConditionBuilder.md
+++ b/help/class_desc/classes/ConditionBuilder.md
@@ -0,0 +1,361 @@
+# Класс `ConditionBuilder`
+
+Класс `ConditionBuilder` предназначен для удобного построения сложных условий запросов к базе данных. Он позволяет
+постепенно наращивать цепь условий, используя цепочечные методы и логические операторы (`AND`, `OR`, `NOT` и т.д.), что
+значительно упрощает формирование SQL-запросов.
+
+## Пространство имён
+
+```php
+namespace goodboyalex\php_db_components_pack\classes;
+```
+
+## Автор и версия
+
+- **Автор**: Александр Бабаев
+- **Версия**: 1.0
+- **Дата начала поддержки**: с версии 1.0
+
+## Назначение
+
+Класс `ConditionBuilder` позволяет гибко составлять сложные условия запросов к базе данных, последовательно добавляя
+условия и логические операторы. Это незаменимый инструмент для быстрого и простого создания запросов, основанных на
+многомерных фильтрах.
+
+## Основные элементы класса
+
+### Составляющие части
+
+- **Логические операторы**: Предусмотрены основные логические операторы (`AND`, `OR`, `NOT`, `XOR`, `NAND`, `NOR`),
+  позволяющие объединять условия с необходимой логической связью.
+- **Группа условий**: Условия могут быть объединены в группы, что позволяет выстраивать сложную иерархию условий.
+- **Защита от SQL-инъекций**: Встроенная защита от SQL-инъекций обеспечивается за счёт возврата готовых параметров
+  запроса.
+
+### Методы
+
+#### 1. Конструктор (`__construct`)
+
+**Назначение**: Создаёт пустой объект, который впоследствии наполняется условиями.
+
+**Синтаксис**:
+
+```php
+public function __construct ();
+```
+
+**Описание**: Создаёт новый экземпляр класса `ConditionBuilder`, который далее будет использован для накопления условий
+и объединения их логическими операторами.
+
+---
+
+#### 2. Метод `Parse`
+
+**Назначение**: Прочитать и разобрать массив условий, созданный вручную или динамически, и создать объект для дальнейшей
+работы.
+
+**Синтаксис**:
+
+```php
+public static function Parse(array $conditions): ConditionBuilder;
+```
+
+**Описание**:
+
+- Метод принимает массив условий и логических операторов.
+- Каждое условие представляется элемент ассоциативного массива, ключом которого является имя столбца, а значение
+  представляет собой массив из (1) оператора и (2) значения.
+- В роли массива значений может выступать и просто значение, тогда за оператор берётся оператор `=`.
+- Логические операторы (`AND`, `OR`, ...) могут находиться между условиями.
+- Пример входящего массива:
+
+```php
+["id" => 1, 'AND', "age" => ['>=', 18], 'OR', "profile" => ['<=', 12]]
+```
+
+- Результатом работы метода является объект `ConditionBuilder`, содержащий всю необходимую информацию для формирования
+  SQL-запроса.
+
+---
+
+#### 3. Метод `AddGroup`
+
+**Назначение**: Добавляет группу условий, объединённых общим логическим оператором.
+
+**Синтаксис**:
+
+```php
+public function AddGroup(string $logicalOperator, array $conditions): ConditionBuilder;
+```
+
+**Описание**:
+
+- **$logicalOperator**: Логический оператор (`AND`, `OR`, и т.д.), который связывает условия в группе.
+- **$conditions**: Массив условий, относящихся к группе.
+- Метод добавляет группу условий и возвращает тот же объект `ConditionBuilder`, позволяя продолжить сборку цепочкой
+  методов.
+
+---
+
+#### 4. Метод `Build`
+
+**Назначение**: Формирует финальную строку SQL-запроса и массив параметров для защиты от SQL-инъекций.
+
+**Синтаксис**:
+
+```php
+public function Build(): Tuple;
+```
+
+**Описание**:
+
+- Метод возвращает кортеж (Tuple), состоящий из двух элементов:
+    - SQL-строка с условием, готовым к выполнению.
+    - Массив параметров, необходимых для последующей передачи в подготовленный SQL-запрос.
+- Позволяет легко интегрировать построенное условие в SQL-запрос.
+
+---
+
+#### 5. Метод `Count`
+
+**Назначение**: Возвращает количество накопленных условий.
+
+**Синтаксис**:
+
+```php
+public function Count(): int;
+```
+
+**Описание**: Метод возвращает целое число, показывающее, сколько условий было собрано на текущий момент.
+
+---
+
+#### 6. Метод `WhereEquals`
+
+**Назначение**: Добавляет условие "равно".
+
+**Синтаксис**:
+
+```php
+public function WhereEquals(string $column, mixed $value): ConditionBuilder;
+```
+
+**Описание**:
+
+- **$column**: Имя колонки.
+- **$value**: Значение, с которым колонка сравнивается.
+- Метод добавляет условие в виде `WHERE column = value` и возвращает объект для продолжения цепочки.
+
+---
+
+#### 7. Метод `WhereNotEquals`
+
+**Назначение**: Добавляет условие "не равно".
+
+**Синтаксис**:
+
+```php
+public function WhereNotEquals(string $column, mixed $value): ConditionBuilder;
+```
+
+**Описание**:
+
+- Аналогичен предыдущему методу, но добавляет условие вида `WHERE column <> value`.
+
+---
+
+#### 8. Метод `WhereGreaterThan`
+
+**Назначение**: Добавляет условие "больше".
+
+**Синтаксис**:
+
+```php
+public function WhereGreaterThan(string $column, mixed $value): ConditionBuilder;
+```
+
+**Описание**:
+
+- Добавляет условие вида `WHERE column > value`.
+
+---
+
+#### 9. Метод `WhereLessThan`
+
+**Назначение**: Добавляет условие "меньше".
+
+**Синтаксис**:
+
+```php
+public function WhereLessThan(string $column, mixed $value): ConditionBuilder;
+```
+
+**Описание**:
+
+- Добавляет условие вида `WHERE column < value`.
+
+---
+
+#### 10. Метод `WhereGreaterThanEqual`
+
+**Назначение**: Добавляет условие "больше или равно".
+
+**Синтаксис**:
+
+```php
+public function WhereGreaterThanEqual(string $column, mixed $value): ConditionBuilder;
+```
+
+**Описание**:
+
+- Добавляет условие вида `WHERE column >= value`.
+
+---
+
+#### 11. Метод `WhereLessThanEqual`
+
+**Назначение**: Добавляет условие "меньше или равно".
+
+**Синтаксис**:
+
+```php
+public function WhereLessThanEqual(string $column, mixed $value): ConditionBuilder;
+```
+
+**Описание**:
+
+- Добавляет условие вида `WHERE column <= value`.
+
+---
+
+#### 12. Метод `AddLogicalOperator`
+
+**Назначение**: Добавляет логический оператор в цепочку условий.
+
+**Синтаксис**:
+
+```php
+public function AddLogicalOperator(string $operator): false|ConditionBuilder;
+```
+
+**Описание**:
+
+- **$operator**: Логический оператор (`AND`, `OR`, `NOT`, `XOR`, `NAND`, `NOR`).
+- Метод добавляет указанный оператор в последовательность условий и возвращает объект для продолжения цепочки. Если
+  оператор неправильный, возвращает `false`.
+
+---
+
+#### 13. Метод `And`
+
+**Назначение**: Добавляет логический оператор `AND`.
+
+**Синтаксис**:
+
+```php
+public function And(): ConditionBuilder;
+```
+
+**Описание**: Удобный аналог метода `AddLogicalOperator`, предназначенный специально для оператора `AND`.
+
+---
+
+#### 14. Метод `Or`
+
+**Назначение**: Добавляет логический оператор `OR`.
+
+**Синтаксис**:
+
+```php
+public function Or(): ConditionBuilder;
+```
+
+**Описание**: Удобный аналог метода `AddLogicalOperator`, предназначенный специально для оператора `OR`.
+
+---
+
+#### 15. Метод `Not`
+
+**Назначение**: Добавляет логический оператор `NOT`.
+
+**Синтаксис**:
+
+```php
+public function Not(): ConditionBuilder;
+```
+
+**Описание**: Удобный аналог метода `AddLogicalOperator`, предназначенный специально для оператора `NOT`.
+
+---
+
+#### 16. Метод `Xor`
+
+**Назначение**: Добавляет логический оператор `XOR`.
+
+**Синтаксис**:
+
+```php
+public function Xor(): ConditionBuilder;
+```
+
+**Описание**: Удобный аналог метода `AddLogicalOperator`, предназначенный специально для оператора `XOR`.
+
+---
+
+#### 17. Метод `Nand`
+
+**Назначение**: Добавляет логический оператор `NAND`.
+
+**Синтаксис**:
+
+```php
+public function Nand(): ConditionBuilder;
+```
+
+**Описание**: Удобный аналог метода `AddLogicalOperator`, предназначенный специально для оператора `NAND`.
+
+---
+
+#### 18. Метод `Nor`
+
+**Назначение**: Добавляет логический оператор `NOR`.
+
+**Синтаксис**:
+
+```php
+public function Nor(): ConditionBuilder;
+```
+
+**Описание**: Удобный аналог метода `AddLogicalOperator`, предназначенный специально для оператора `NOR`.
+
+## Пример использования
+
+Допустим, у вас есть задача отобрать пользователей, чей возраст превышает 18 лет и они зарегистрированы позже
+определённой даты:
+
+```php
+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();
+```
+
+В результате можно будет создать такой запрос:
+
+```sql
+SELECT *
+FROM `TABLE`
+WHERE (`age` > 18)
+  AND (`registration_date` > '2023-01-01');
+```
+
+## Принцип работы
+
+Класс `ConditionBuilder` постепенно аккумулирует условия, создавая дерево зависимостей, состоящее из условий и
+логических операторов. За счёт этого появляется возможность легко создавать и редактировать сложные фильтры для запросов
+к базе данных.
+
+[На главную](../../index.md)