20250807

help/class_desc/classes/ConditionGroup.md

@@ -0,0 +1,86 @@
+# Класс `ConditionGroup`
+
+Класс `ConditionGroup` предназначен для группировки условий в SQL-запросах, позволяя комбинировать отдельные условия с
+помощью логических операторов (`AND`, `OR`, `NOT`, и т.д.) и формировать единое сложное выражение для использования в
+запросах к базе данных.
+
+## Пространство имён
+
+```php
+namespace goodboyalex\php_db_components_pack\classes;
+```
+
+## Автор и версия
+
+- **Автор**: Александр Бабаев
+- **Версия**: 1.0
+- **Дата начала поддержки**: с версии 1.0
+
+## Назначение
+
+Класс `ConditionGroup` позволяет группировать условия и соединять их логическим оператором, формируя составные условия
+для SQL-запросов. Это особенно полезно, когда нужно объединить несколько простых условий в одно комплексное.
+
+## Важно
+
+Все условия, входящие в `ConditionGroup` должны быть объеденины **одним единственным оператором**. То есть, вот такое
+условие не объединить в `ConditionGroup`:
+
+```
+(условие 1 AND условие 2 OR условие 3)
+```
+
+Для реализации такого условия, какие-то из условий должны быть заключены в подгруппу.
+
+## Основные методы класса
+
+1. **Конструктор (`__construct`)**  
+   Создаёт объект группы условий с возможностью указания логического оператора и самих условий.
+
+2. **Формирование условий (`GetConditions`)**  
+   Формирует итоговую группу условий в виде пары: SQL-строка и массив параметров для безопасной передачи в запрос.
+
+3. **Количество условий (`Count`)**  
+   Возвращает количество условий в группе.
+
+## Пример использования
+
+Допустим, у вас есть две группы условий: первая группа ищет пользователей от 18 и до 45 лет, вторая — пользователей с
+правами администратора или модератора. Вы хотите объединить эти условия с помощью оператора `OR`:
+
+```php
+use goodboyalex\php_components_pack\Condition;
+use goodboyalex\php_components_pack\ConditionGroup;
+
+// Первая группа условий: пользователи от 18 до 45 лет
+$group1 = new ConditionGroup(Condition::LOGIC_AND, [
+    new Condition('age', '>=', 18),
+    new Condition('age', '<=', 45)
+]);
+
+// Вторая группа условий: администраторы
+$group2 = new ConditionGroup(Condition::LOGIC_OR, [
+    new Condition('role', '=', 'admin'),
+    new Condition('role', '=', 'moderator')
+]);
+
+// Объединяем обе группы с оператором OR
+$combinedGroup = new ConditionGroup(Condition::LOGIC_OR, [
+    $group1,
+    $group2
+]);
+```
+
+Группа `$combinedGroup` равносильна такому ограничению:
+
+```
+((`age` >= 18) AND (`age` <= 45)) OR ((`role`='admin') OR (`role`='moderator'))
+```
+
+## Принцип работы
+
+Класс `ConditionGroup` собирает отдельные условия в группы и соединяет их с помощью логических операторов. Затем с
+помощью метода `GetConditions` формируются готовые SQL-условия, подходящие для встраивания в запрос с поддержкой
+механизма подставляемых параметров (placeholders), что обеспечивает защиту от SQL-инъекций.
+
+[На главную](../../index.md)