# Класс `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)