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