20250807

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)