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/Condition.md
+++ b/help/class_desc/classes/Condition.md
@@ -0,0 +1,158 @@
+# Класс `Condition`
+
+Класс `Condition` предназначен для представления условий, используемых в запросах к базе данных. Он позволяет построить
+выражения для фильтрации данных на основе логических операторов и критериев.
+
+## Пространство имён
+
+```php
+namespace goodboyalex\php_db_components_pack;
+```
+
+## Автор и версия
+
+- **Автор**: Александр Бабаев
+- **Версия**: 1.0
+- **Дата начала поддержки**: с версии 1.0
+
+## Назначение
+
+Класс `Condition` предназначен для создания и представления условий, используемых в SQL-запросах. Он позволяет задавать
+критерии фильтрации, объединять их логическими операторами и формировать готовые SQL-выражения для безопасного
+исполнения запросов.
+
+## Реализуемые интерфейсы
+
+Класс `Condition` реализует интерфейс `IArrayable`.
+
+## Логические операторы
+
+Класс предоставляет ряд постоянных, определяющих логические операторы, которые могут быть использованы при формировании
+условий:
+
+- `LOGIC_AND` («И», AND)
+- `LOGIC_OR` («ИЛИ», OR)
+- `LOGIC_NOT` («НЕ», NOT)
+- `LOGIC_XOR` («Исключающее ИЛИ», XOR)
+- `LOGIC_NAND` («Нелогичное И», NAND)
+- `LOGIC_NOR` («Нелогичное ИЛИ», NOR)
+
+## Методы класса
+
+### 1. Конструктор
+
+**Назначение**: Создать объект условия с заданием имени колонки, оператора и значения.
+
+**Синтаксис**:
+
+```php
+public function __construct (
+    string $columnName = "",
+    string $operator = "=",
+    mixed $value = null
+);
+```
+
+**Описание**:
+
+- **$columnName**: Имя колонки, к которой применяется условие ИЛИ условие (подробнее читайте далее в пункте про
+  `FUNC:`).
+- **$operator**: Оператор сравнения (например, `=`, `<>`, `<`, `>`, `LIKE`, etc.). Стандартное значение — `=` (
+  равенство).
+- **$value**: Значение, с которым производится сравнение ИЛИ результат вычисления функции (подробнее читайте далее в
+  пункте про `FUNC:`).
+
+**Пример использования**:
+
+```php
+$condition = new Condition('age', '>', 18);
+```
+
+#### Задание условий с помощью функции (`FUNC:`)
+
+Если в имени колонки передаётся какая-либо функция (начинать такую функцию следует с `FUNC:`), то при обработке она 
+не обрабатывается как столбец. Это же касается и значения.
+
+Например, давайте добавим условие, что каждое новое имя пользователя начинается с заглавной буквы
+
+```php
+use goodboyalex\php_db_components_pack\classes\Condition;
+
+$condition = new Condition('FUNC:SUBSTR(name, 1, 1)', "=", 'FUNC:UPPER(SUBSTR(name, 1, 1))
+```
+
+в результате запрос будет содержать:
+```sql
+SUBSTR(name, 1, 1) = UPPER(SUBSTR(name, 1, 1)
+```
+
+### 2. Метод `Parse`
+
+**Назначение**: Разобрать условие, заданное в виде массива, и возвратить объект `Condition`.
+
+**Синтаксис**:
+
+```php
+public static function Parse(array $condition): Condition;
+```
+
+**Описание**:
+
+- **$condition**: Массив, содержащий три элемента: имя колонки, оператор и значение.
+- Метод преобразует массив в полноценный объект `Condition`.
+
+**Пример использования**:
+
+```php
+$parsedCondition = Condition::Parse(['age', '>', 18]);
+```
+
+### 3. Метод `Get`
+
+**Назначение**: Сформировать условие для SQL-запроса с защитой от SQL-инъекций.
+
+**Синтаксис**:
+
+```php
+public function Get(int $index = 0): Tuple;
+```
+
+**Описание**:
+
+- **$index**: Индексация для замены переменных (для предотвращения SQL-инъекций).
+- Метод возвращает кортеж (tuple), состоящий из двух частей:
+    - SQL-строку с замещаемым параметром (`:paramX`), где X — номер индекса.
+    - Массив с параметрами для последующего внедрения в запрос.
+
+**Пример использования**:
+
+```php
+[$sqlPart, $params] = $condition->Get();
+// $sqlPart будет выглядеть примерно так: "`age` > :param0"
+// $params будет содержать массив с фактическим значением: ["param0" => 18]
+```
+
+## Пример использования
+
+```php
+use goodboyalex\php_db_components_pack\Condition;
+
+// Создаём условие для поиска пользователей по возрасту
+$condition = new Condition('age', '>', 18);
+
+// Формируем условие для использования в SQL-запросе
+list($sql, $parameters) = $condition->Get();
+
+// Теперь можем использовать $sql и $parameters в запросе
+$query = "SELECT * FROM users WHERE $sql";
+$stmt = $pdo->prepare($query);
+$stmt->execute($parameters);
+```
+
+## Принцип работы
+
+Класс `Condition` помогает избежать распространенных уязвимостей, таких как SQL-инъекции, предлагая безопасный способ
+формирования условий для SQL-запросов. Он активно используется в условиях запросов к базе данных, позволяя разработчику
+сосредоточиться на логике приложения, а не на технических аспектах формирования запросов.
+
+[На главную](../../index.md)
--- 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)
--- a/help/class_desc/classes/ConditionGroup.md
+++ b/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)