babaev-an/php_db_components_pack
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
php_db_components_pack/help/class_desc/classes/ConditionBuilder.md
babaev-an 3dc403ebf2 20250810 v1.0
2025-08-10 11:48:29 +03:00

19 KiB
Raw Blame History

Класс ConditionBuilder

Класс ConditionBuilder предназначен для удобного построения сложных условий запросов к базе данных. Он позволяет постепенно наращивать цепь условий, используя цепочечные методы и логические операторы (AND, OR, NOT и т.д.), что значительно упрощает формирование SQL-запросов.

Пространство имён

namespace goodboyalex\php_db_components_pack\classes;

Автор и версия

  • Автор: Александр Бабаев
  • Версия: 1.0
  • Дата начала поддержки: с версии 1.0

Назначение

Класс ConditionBuilder позволяет гибко составлять сложные условия запросов к базе данных, последовательно добавляя условия и логические операторы. Это незаменимый инструмент для быстрого и простого создания запросов, основанных на многомерных фильтрах.

Основные элементы класса

Составляющие части

  • Логические операторы: Предусмотрены основные логические операторы (AND, OR, NOT, XOR, NAND, NOR), позволяющие объединять условия с необходимой логической связью.
  • Группа условий: Условия могут быть объединены в группы, что позволяет выстраивать сложную иерархию условий.
  • Защита от SQL-инъекций: Встроенная защита от SQL-инъекций обеспечивается за счёт возврата готовых параметров запроса.

Методы

1. Конструктор (__construct)

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

Синтаксис:

public function __construct ();

Описание: Создаёт новый экземпляр класса ConditionBuilder, который далее будет использован для накопления условий и объединения их логическими операторами.

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

// Будет создано новое пустое условие
$builder = new ConditionBuilder();

2. Метод Parse

Назначение: Прочитать и разобрать массив условий, созданный вручную или динамически, и создать объект для дальнейшей работы.

Синтаксис:

public static function Parse(array $conditions): ConditionBuilder;

Описание:

  • Метод принимает массив условий и логических операторов.
  • Каждое условие представляется элемент ассоциативного массива, ключом которого является имя столбца, а значение представляет собой массив из (1) оператора и (2) значения.
  • В роли массива значений может выступать и просто значение, тогда за оператор берётся оператор =.
  • Логические операторы (AND, OR, ...) могут находиться между условиями.
  • Пример входящего массива:
["id" => 1, 'AND', "age" => ['>=', 18], 'OR', "profile" => ['<=', 12]]
  • Результатом работы метода является объект ConditionBuilder, содержащий всю необходимую информацию для формирования SQL-запроса.

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

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

3. Метод AddGroup

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

Синтаксис:

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

Описание:

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

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

// Будет создана группа: ((`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-инъекций.

Синтаксис:

public function Build(): Tuple;

Описание:

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

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

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

5. Метод Count

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

Синтаксис:

public function Count(): int;

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

// Будет создан шаблон: (`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

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

Синтаксис:

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

Описание:

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

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

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

7. Метод WhereNotEquals

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

Синтаксис:

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

Описание:

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

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

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

8. Метод WhereGreaterThan

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

Синтаксис:

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

Описание:

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

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

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

9. Метод WhereLessThan

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

Синтаксис:

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

Описание:

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

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

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

10. Метод WhereGreaterThanEqual

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

Синтаксис:

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

Описание:

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

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

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

11. Метод WhereLessThanEqual

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

Синтаксис:

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

Описание:

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

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

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

12. Метод WhereLike

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

Синтаксис:

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

Описание:

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

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

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

13. Метод AddCondition

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

Синтаксис:

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

Описание:

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

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

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

14. Метод AddLogicalOperator

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

Синтаксис:

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

Описание:

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

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

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

15. Метод And

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

Синтаксис:

public function And(): ConditionBuilder;

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

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

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

16. Метод Or

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

Синтаксис:

public function Or(): ConditionBuilder;

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

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

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

17. Метод Not

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

Синтаксис:

public function Not(): ConditionBuilder;

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

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

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

18. Метод Xor

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

Синтаксис:

public function Xor(): ConditionBuilder;

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

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

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

19. Метод Nand

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

Синтаксис:

public function Nand(): ConditionBuilder;

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

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

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

20. Метод Nor

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

Синтаксис:

public function Nor(): ConditionBuilder;

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

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

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

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

Допустим, у вас есть задача отобрать пользователей, чей возраст превышает 18 лет и они зарегистрированы позже определённой даты:

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();

В результате можно будет создать такой запрос:

SELECT *
FROM `TABLE`
WHERE (`age` > 18)
  AND (`registration_date` > '2023-01-01');

Принцип работы

Класс ConditionBuilder постепенно аккумулирует условия, создавая дерево зависимостей, состоящее из условий и логических операторов. За счёт этого появляется возможность легко создавать и редактировать сложные фильтры для запросов к базе данных.

На главную