20250810 v1.0

2025-08-10 11:48:29 +03:00
parent d2077fbc76
commit 3dc403ebf2
11 changed files with 426 additions and 19 deletions
--- a/help/class_desc/classes/ConditionBuilder.md
+++ b/help/class_desc/classes/ConditionBuilder.md
@@ -47,6 +47,13 @@ public function __construct ();
 **Описание**: Создаёт новый экземпляр класса `ConditionBuilder`, который далее будет использован для накопления условий
 и объединения их логическими операторами.

+**Пример использования**:
+
+```php
+// Будет создано новое пустое условие
+$builder = new ConditionBuilder();
+```
+
 ---

 #### 2. Метод `Parse`
@@ -76,6 +83,13 @@ public static function Parse(array $conditions): ConditionBuilder;
 - Результатом работы метода является объект `ConditionBuilder`, содержащий всю необходимую информацию для формирования
  SQL-запроса.

+**Пример использования**:
+
+```php
+// Будет создан шаблон: (`id` = 1) AND (`age` >= 18) OR (`profile` <= 12) 
+$builder = ConditionBuilder::Parse(["id" => 1, 'AND', "age" => ['>=', 18], 'OR', "profile" => ['<=', 12]]);
+```
+
 ---

 #### 3. Метод `AddGroup`
@@ -95,6 +109,13 @@ public function AddGroup(string $logicalOperator, array $conditions): ConditionB
 - Метод добавляет группу условий и возвращает тот же объект `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`
@@ -114,6 +135,13 @@ public function Build(): Tuple;
    - Массив параметров, необходимых для последующей передачи в подготовленный SQL-запрос.
 - Позволяет легко интегрировать построенное условие в SQL-запрос.

+**Пример использования**:
+
+```php
+// $sql будет (`age` >= :age), а params - [':age' = 18]
+[$sql, $params] = new ConditionBuilder()->AddCondition('age', '>=', 18)->Build();
+```
+
 ---

 #### 5. Метод `Count`
@@ -128,6 +156,14 @@ 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`
@@ -146,6 +182,13 @@ public function WhereEquals(string $column, mixed $value): ConditionBuilder;
 - **$value**: Значение, с которым колонка сравнивается.
 - Метод добавляет условие в виде `WHERE column = value` и возвращает объект для продолжения цепочки.

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

 #### 7. Метод `WhereNotEquals`
@@ -162,6 +205,13 @@ public function WhereNotEquals(string $column, mixed $value): ConditionBuilder;

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

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

 #### 8. Метод `WhereGreaterThan`
@@ -178,6 +228,13 @@ public function WhereGreaterThan(string $column, mixed $value): ConditionBuilder

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

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

 #### 9. Метод `WhereLessThan`
@@ -194,6 +251,13 @@ public function WhereLessThan(string $column, mixed $value): ConditionBuilder;

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

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

 #### 10. Метод `WhereGreaterThanEqual`
@@ -210,6 +274,13 @@ public function WhereGreaterThanEqual(string $column, mixed $value): ConditionBu

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

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

 #### 11. Метод `WhereLessThanEqual`
@@ -226,9 +297,65 @@ public function WhereLessThanEqual(string $column, mixed $value): ConditionBuild

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

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

-#### 12. Метод `AddLogicalOperator`
+#### 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`

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

@@ -244,9 +371,16 @@ public function AddLogicalOperator(string $operator): false|ConditionBuilder;
 - Метод добавляет указанный оператор в последовательность условий и возвращает объект для продолжения цепочки. Если
  оператор неправильный, возвращает `false`.

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

-#### 13. Метод `And`
+#### 15. Метод `And`

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

@@ -258,9 +392,16 @@ public function And(): ConditionBuilder;

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

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

-#### 14. Метод `Or`
+#### 16. Метод `Or`

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

@@ -272,9 +413,16 @@ public function Or(): ConditionBuilder;

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

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

-#### 15. Метод `Not`
+#### 17. Метод `Not`

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

@@ -286,9 +434,16 @@ public function Not(): ConditionBuilder;

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

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

-#### 16. Метод `Xor`
+#### 18. Метод `Xor`

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

@@ -300,9 +455,16 @@ public function Xor(): ConditionBuilder;

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

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

-#### 17. Метод `Nand`
+#### 19. Метод `Nand`

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

@@ -314,9 +476,16 @@ public function Nand(): ConditionBuilder;

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

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

-#### 18. Метод `Nor`
+#### 20. Метод `Nor`

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

@@ -328,6 +497,13 @@ public function Nor(): ConditionBuilder;

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

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

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