# Класс `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`, который далее будет использован для накопления условий
и объединения их логическими операторами.

**Пример использования**:

```php
// Будет создано новое пустое условие
$builder = new 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-запроса.

**Пример использования**:

```php
// Будет создан шаблон: (`id` = 1) AND (`age` >= 18) OR (`profile` <= 12) 
$builder = ConditionBuilder::Parse(["id" => 1, 'AND', "age" => ['>=', 18], 'OR', "profile" => ['<=', 12]]);
```

---

#### 3. Метод `AddGroup`

**Назначение**: Добавляет группу условий, объединённых общим логическим оператором.

**Синтаксис**:

```php
public function AddGroup(string $logicalOperator, array $conditions): ConditionBuilder;
```

**Описание**:

- **$logicalOperator**: Логический оператор (`AND`, `OR`, и т.д.), который связывает условия в группе.
- **$conditions**: Массив условий, относящихся к группе.
- Метод добавляет группу условий и возвращает тот же объект `ConditionBuilder`, позволяя продолжить сборку цепочкой
  методов.

**Пример использования**:

```php
// Будет создана группа: ((`age` >= 18) OR (`group` = 'admin')) 
$builder = new ConditionBuilder()->AddGroup(Condition::LOGIC_OR, [new Condition('age', '>=', 18), new Condition('group', value: 'admin')]);
```

---

#### 4. Метод `Build`

**Назначение**: Формирует финальную строку SQL-запроса и массив параметров для защиты от SQL-инъекций.

**Синтаксис**:

```php
public function Build(): Tuple;
```

**Описание**:

- Метод возвращает кортеж (Tuple), состоящий из двух элементов:
    - SQL-строка с условием, готовым к выполнению.
    - Массив параметров, необходимых для последующей передачи в подготовленный SQL-запрос.
- Позволяет легко интегрировать построенное условие в SQL-запрос.

**Пример использования**:

```php
// $sql будет (`age` >= :age), а params - [':age' = 18]
[$sql, $params] = new ConditionBuilder()->AddCondition('age', '>=', 18)->Build();
```

---

#### 5. Метод `Count`

**Назначение**: Возвращает количество накопленных условий.

**Синтаксис**:

```php
public function Count(): int;
```

**Описание**: Метод возвращает целое число, показывающее, сколько условий было собрано на текущий момент.

```php
// Будет создан шаблон: (`id` = 1) AND (`age` >= 18) OR (`profile` <= 12) 
$builder = ConditionBuilder::Parse(["id" => 1, 'AND', "age" => ['>=', 18], 'OR', "profile" => ['<=', 12]]);

// Выведет 3
echo $builder->Count();
```

---

#### 6. Метод `WhereEquals`

**Назначение**: Добавляет условие "равно".

**Синтаксис**:

```php
public function WhereEquals(string $column, mixed $value): ConditionBuilder;
```

**Описание**:

- **$column**: Имя колонки.
- **$value**: Значение, с которым колонка сравнивается.
- Метод добавляет условие в виде `WHERE column = value` и возвращает объект для продолжения цепочки.

**Пример использования**:

```php
// Будет соответствовать имени пользователя "Ivan"
$builder = new ConditionBuilder()->WhereEquals('username', 'Ivan');
```

---

#### 7. Метод `WhereNotEquals`

**Назначение**: Добавляет условие "не равно".

**Синтаксис**:

```php
public function WhereNotEquals(string $column, mixed $value): ConditionBuilder;
```

**Описание**:

- Аналогичен предыдущему методу, но добавляет условие вида `WHERE column <> value`.

**Пример использования**:

```php
// Будет соответствовать любому имени пользователя, кроме "Ivan"
$builder = new ConditionBuilder()->WhereNotEquals('username', 'Ivan');
```

---

#### 8. Метод `WhereGreaterThan`

**Назначение**: Добавляет условие "больше".

**Синтаксис**:

```php
public function WhereGreaterThan(string $column, mixed $value): ConditionBuilder;
```

**Описание**:

- Добавляет условие вида `WHERE column > value`.

**Пример использования**:

```php
// Будет соответствовать любому возрасту старше 65 лет
$builder = new ConditionBuilder()->WhereGreaterThan('age', 65);
```

---

#### 9. Метод `WhereLessThan`

**Назначение**: Добавляет условие "меньше".

**Синтаксис**:

```php
public function WhereLessThan(string $column, mixed $value): ConditionBuilder;
```

**Описание**:

- Добавляет условие вида `WHERE column < value`.

**Пример использования**:

```php
// Будет соответствовать любому возрасту младше 40 лет
$builder = new ConditionBuilder()->WhereLessThan('age', 40);
```

---

#### 10. Метод `WhereGreaterThanEqual`

**Назначение**: Добавляет условие "больше или равно".

**Синтаксис**:

```php
public function WhereGreaterThanEqual(string $column, mixed $value): ConditionBuilder;
```

**Описание**:

- Добавляет условие вида `WHERE column >= value`.

**Пример использования**:

```php
// Будет соответствовать любому возрасту от 18 лет
$builder = new ConditionBuilder()->WhereGreaterThanEqual('age', 18);
```

---

#### 11. Метод `WhereLessThanEqual`

**Назначение**: Добавляет условие "меньше или равно".

**Синтаксис**:

```php
public function WhereLessThanEqual(string $column, mixed $value): ConditionBuilder;
```

**Описание**:

- Добавляет условие вида `WHERE column <= value`.

**Пример использования**:

```php
// Будет соответствовать любому возрасту до 65 лет
$builder = new ConditionBuilder()->WhereLessThanEqual('age', 65);
```

---

#### 12. Метод `WhereLike`

**Назначение**: Добавляет условие типа LIKE для поиска частичных совпадений в базе данных.

**Синтаксис**:

```php
public function WhereLike(string $column, string $value): ConditionBuilder;
```

**Описание**:
- **$column**: Имя колонки, по которой проводится поиск.
- **$value**: Шаблон для поиска (обычно включает символы `%` для указания маски).
- Метод добавляет условие в виде `WHERE column LIKE '%value%'` и возвращает объект для продолжительного построения условий.

**Пример использования**:

```php
// Будет соответствовать любому имени пользователя, содержащему "нович"
$builder = new ConditionBuilder()->WhereLike('username', '%нович%');
```

---

#### 13. Метод `AddCondition`

**Назначение**: Добавляет универсальное условие с любым заданным оператором.

**Синтаксис**:

```php
public function AddCondition(string $column, string $operator, mixed $value): ConditionBuilder;
```

**Описание**:
- **$column**: Имя колонки, участвующей в условии.
- **$operator**: Любой оператор сравнения (например, `=`, `!=`, `<`, `>`, `IN`, `BETWEEN`, и т.д.).
- **$value**: Значение, с которым производится сравнение.
- Метод добавляет условие в форме `WHERE column OPERATOR value` и возвращает объект для продолжения построения цепочки условий.

**Пример использования**:

```php
// Только совершеннолетние пользователи
$builder = new ConditionBuilder()->AddCondition('age', '>=', 18);
```

---

#### 14. Метод `AddLogicalOperator`

**Назначение**: Добавляет логический оператор в цепочку условий.

**Синтаксис**:

```php
public function AddLogicalOperator(string $operator): false|ConditionBuilder;
```

**Описание**:

- **$operator**: Логический оператор (`AND`, `OR`, `NOT`, `XOR`, `NAND`, `NOR`).
- Метод добавляет указанный оператор в последовательность условий и возвращает объект для продолжения цепочки. Если
  оператор неправильный, возвращает `false`.

**Пример использования**:

```php
// Добавляет оператор OR между условиями '(`age` >= 18)' и '(`age` <= 65)' 
$builder = new ConditionBuilder()->WhereGreaterThanEqual('age', 18)->AddLogicalOperator('OR')->WhereLessThanEqual('age', 65);
```

---

#### 15. Метод `And`

**Назначение**: Добавляет логический оператор `AND`.

**Синтаксис**:

```php
public function And(): ConditionBuilder;
```

**Описание**: Удобный аналог метода `AddLogicalOperator`, предназначенный специально для оператора `AND`.

**Пример использования**:

```php
// Добавляет оператор AND между условиями '(`age` >= 18)' и '(`age` <= 65)' 
$builder = new ConditionBuilder()->WhereGreaterThanEqual('age', 18)->And()->WhereLessThanEqual('age', 65);
```

---

#### 16. Метод `Or`

**Назначение**: Добавляет логический оператор `OR`.

**Синтаксис**:

```php
public function Or(): ConditionBuilder;
```

**Описание**: Удобный аналог метода `AddLogicalOperator`, предназначенный специально для оператора `OR`.

**Пример использования**:

```php
// Добавляет оператор OR между условиями '(`age` >= 18)' и '(`age` <= 65)' 
$builder = new ConditionBuilder()->WhereGreaterThanEqual('age', 18)->Or()->WhereLessThanEqual('age', 65);
```

---

#### 17. Метод `Not`

**Назначение**: Добавляет логический оператор `NOT`.

**Синтаксис**:

```php
public function Not(): ConditionBuilder;
```

**Описание**: Удобный аналог метода `AddLogicalOperator`, предназначенный специально для оператора `NOT`.

**Пример использования**:

```php
// Добавляет оператор NOT перед условием '(`age` >= 18)' 
$builder = new ConditionBuilder()->Not()->WhereGreaterThanEqual('age', 18);
```

---

#### 18. Метод `Xor`

**Назначение**: Добавляет логический оператор `XOR`.

**Синтаксис**:

```php
public function Xor(): ConditionBuilder;
```

**Описание**: Удобный аналог метода `AddLogicalOperator`, предназначенный специально для оператора `XOR`.

**Пример использования**:

```php
// Добавляет оператор XOR между условиями '(`age` >= 18)' и '(`age` <= 65)' 
$builder = new ConditionBuilder()->WhereGreaterThanEqual('age', 18)->Xor()->WhereLessThanEqual('age', 65);
```

---

#### 19. Метод `Nand`

**Назначение**: Добавляет логический оператор `NAND`.

**Синтаксис**:

```php
public function Nand(): ConditionBuilder;
```

**Описание**: Удобный аналог метода `AddLogicalOperator`, предназначенный специально для оператора `NAND`.

**Пример использования**:

```php
// Добавляет оператор NAND между условиями '(`age` >= 18)' и '(`age` <= 65)' 
$builder = new ConditionBuilder()->WhereGreaterThanEqual('age', 18)->Nand()->WhereLessThanEqual('age', 65);
```

---

#### 20. Метод `Nor`

**Назначение**: Добавляет логический оператор `NOR`.

**Синтаксис**:

```php
public function Nor(): ConditionBuilder;
```

**Описание**: Удобный аналог метода `AddLogicalOperator`, предназначенный специально для оператора `NOR`.

**Пример использования**:

```php
// Добавляет оператор NOR между условиями '(`age` >= 18)' и '(`age` <= 65)' 
$builder = new ConditionBuilder()->WhereGreaterThanEqual('age', 18)->Nor()->WhereLessThanEqual('age', 65);
```

## Пример использования

Допустим, у вас есть задача отобрать пользователей, чей возраст превышает 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)