babaev-an/php_db_components_pack
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

20250810 v1.0

Browse Source
This commit is contained in:
Александр Бабаев 2025-08-10 11:48:29 +03:00
parent d2077fbc76
commit 3dc403ebf2
11 changed files with 426 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
help/basic_usage/count_exist_data.md Normal file
View File

@ -0,0 +1,39 @@
# Пороверка существования данных и их количество
Итак, в [прошлой статье](get_data.md) мы получали данные из таблицы `users`. Напомним, что она имеет вид:
| id | user_name | user_mail |
|:--:|:---------:|:-------------------:|
| 1 | Ivan | ivan@example.com |
| 2 | Olga | olga@example.com |
| 3 | Oleg | oleg@mail.ru |
| 4 | Nikolay | nikolay@example.com |
Попробуем теперь проверить, есть ли в таблице пользователь`Oleg`. Для этого воспользуемся
методом [IsExist](../class_desc/classes/Database.md#72-проверка-существования-записей-isexist):
```php
$userExist = $db->IsExist('users', new ConditionBuilder()->WhereEquals('user_name', 'Oleg'));
// Выведет "Он существует!"
if (userExist)
echo 'Он существует!';
```
Давайте теперь посчитаем количество всех пользователей и тех, у которых почта на домене `example.com`. Для этого нам
потребуется метод [Count](../class_desc/classes/Database.md#71-подсчет-записей-count):
```php
// Все пользователи
$allUsers = $db->Count('users');
// Пользователи, у которых почта на домене `example.com`
$exampleUsers = $db->Count('users', new ConditionBuilder()->WhereLike('user_mail', '%example.com'));
// Выведет: 3/4
echo "$exampleUsers/$allUsers";
```
Итак, мы рассмотрели способы проверки существования данных и подсчёта количества данных по условию.
[Предыдущий пункт](get_data.md) | [На главную](../index.md) | [Следующий пункт](update_data.md)

11
help/basic_usage/create_table.md
View File

@ -81,7 +81,16 @@ class User implements IDBItem
Значения во всех столбцах, кроме `user_name` должны быть уникальными, во всех столбцах не пустыми, а первичным ключом
таблицы является столбец `id` с автозаполнением.
Теперь давайте создадим таблицу `user`:
Теперь давайте создадим таблицу `user`. Сперва давайте проверим, существует ли такая таблица в БД. В этом нам поможет
метод [IsTableExist](../class_desc/classes/Database.md#101-проверка-существования-таблицы-istableexist):
```php
if ($db->IsTableExist('user'))
throw new PDOException("Ты чего это удумал? Таблица users уже существует!");
```
Итак, таблицы нет и мы можем воспользоваться
методом [CreateTable](../class_desc/classes/Database.md#102-создание-таблицы-createtable) для её создания:
```php
if (!$db->CreateTable('user', "\\App\\Models\\User"))

44
help/basic_usage/delete_data.md Normal file
View File

@ -0,0 +1,44 @@
# Удаление данных
Итак, в [прошлой статье](update_data.md) мы обновляли данные в таблице `users`. Теперь она имеет вид:
| id | user_name | user_mail |
|:--:|:---------:|:-----------------:|
| 1 | Ivan | ivan@yandex.ru |
| 2 | Olga | olga@ya.ru |
| 3 | Oleg | oleg@mail.ru |
| 4 | Nikolay | nikolay@yandex.ru |
Попробуем теперь удалить строку, где имя пользователя - `Oleg`. Для этого воспользуемся
методом [Delete](../class_desc/classes/Database.md#9-удаление-записей-delete):
```php
if ($db->Delete('users', new ConditionBuilder()->WhereEquals('user_name', 'Oleg')))
echo 'Oleg больше не с нами!';
```
Теперь таблица имеет вид:
| id | user_name | user_mail |
|:--:|:---------:|:-----------------:|
| 1 | Ivan | ivan@yandex.ru |
| 2 | Olga | olga@ya.ru |
| 4 | Nikolay | nikolay@yandex.ru |
Удалять можно не только одну запись. Например, давайте удалим всех пользователей, у которых почта находится на
`yandex.ru`:
```php
if ($db->Delete('users', new ConditionBuilder()->WhereLike('user_mail', '%yandex.ru')))
echo 'Пользователи yandex.ru теперь не с нами!';
```
Теперь таблица имеет вид:
| id | user_name | user_mail |
|:--:|:---------:|:----------:|
| 2 | Olga | olga@ya.ru |
Итак, мы рассмотрели все возможные способы удаления данных.
[Предыдущий пункт](update_data.md) | [На главную](../index.md) | [Следующий пункт](drop_table.md)

14
help/basic_usage/drop_table.md Normal file
View File

@ -0,0 +1,14 @@
# Удаление таблицы
Итак, в [прошлой статье](delete_data.md) мы удаляли данные из таблицы `users`. Теперь же мы хотим полностью удалить её.
Для этого воспользуемся методом [DropTable](../class_desc/classes/Database.md#103-удаление-таблицы-droptable):
```php
if ($db->DropTable('users'))
echo 'Нет у нас больше пользователей =(';
```
После удаления, таблицы не будет в базе данных. Итак, мы рассмотрели все возможные способы работы с данными и таблицами
в классе [Database](../class_desc/classes/Database.md).
[Предыдущий пункт](delete_data.md) | [На главную](../index.md)

50
help/basic_usage/get_data.md
View File

@ -13,12 +13,54 @@
методом [GetRow](../class_desc/classes/Database.md#61-получение-одного-объекта-getrow):
```php
use goodboyalex\php_db_components_pack\classes\ConditionBuilder;
$user = $db->GetRow('users', where: new ConditionBuilder()->WhereEquals('user_name', 'Oleg'), className: "\\App\\Models\\User")
$user = $db->GetRow('users', where: new ConditionBuilder()->WhereEquals('user_name', 'Oleg'), className: "\\App\\Models\\User");
echo $user->Id; // Выведет 3
echo $user->Email; // Выведет oleg@mail.ru
```
[Предыдущий пункт](insert_data.md) | [На главную](../index.md) | [Следующий пункт](../index.md)
Давайте теперь получим пользователей, у которых почта на домене `example.com`. Для этого нам потребуется
метод [GetRows](../class_desc/classes/Database.md#62-получение-набора-объектов-getrows):
```php
$users = $db->GetRows('users', where: new ConditionBuilder()->WhereLike('user_mail', '%example.com'), className: "\\App\\Models\\User");
// Выведет:
// Ivan
// Olga
// Nikolay
foreach ($users as $user)
echo $user->Name;
```
Давайте теперь немного изменим предыдущую задачу. Пусть нам требуется только столбец `user_name` для всех пользователей.
Для этого нам потребуется метод [GetCol](../class_desc/classes/Database.md#63-получение-столбца-getcol):
```php
$users = $db->GetCol('users', 'user_name');
$users = implode(', ', $users);
// Выведет: Ivan, Olga, Oleg, Nikolay
echo $users;
```
Далее, представим, что вы пишете функцию получения `id` по `user_name`. С помощью
метода [GetValue](../class_desc/classes/Database.md#64-получение-одиночного-значения-getvalue) мы это сделаем ниже:
```php
function GetUserId (string $userName): int {
// Задаём условие
$condition = new ConditionBuilder()->WhereEquals('user_name', $userName);
// Получаем
$id = $db->GetValue('users', 'id', $condition);
// Возвращаю 0, если ошибка и $id, если всё хорошо
return $id == null ? 0 : $id;
}
```
Итак, мы рассмотрели все возможные способы получения данных.
[Предыдущий пункт](insert_data.md) | [На главную](../index.md) | [Следующий пункт](update_data.md)

66
help/basic_usage/update_data.md Normal file
View File

@ -0,0 +1,66 @@
# Обновление данных
Итак, в [прошлой статье](count_exist_data.md) мы рассмотрели способы проверки существования данных и подсчёта количества
данных по условию из таблицы `users`. Напомним, что она имеет вид:
| id | user_name | user_mail |
|:--:|:---------:|:-------------------:|
| 1 | Ivan | ivan@example.com |
| 2 | Olga | olga@example.com |
| 3 | Oleg | oleg@mail.ru |
| 4 | Nikolay | nikolay@example.com |
Попробуем теперь изменить почту пользователя `Olga`. Для этого воспользуемся
методом [Update](../class_desc/classes/Database.md#81-обновление-одной-записи-update):
```php
// Давайте получим сперва пользователя
$user = $db->GetRow('users', where: new ConditionBuilder()->WhereEquals('user_name', 'Olga'), className: "\\App\\Models\\User");
// Меняем почту
$user->Email = 'olga@ya.ru'
if ($db->Update('users', $user))
echo 'Почта Ольги обновлена!';
```
Теперь таблица в БД имеет вид:
| id | user_name | user_mail |
|:--:|:---------:|:-------------------:|
| 1 | Ivan | ivan@example.com |
| 2 | Olga | olga@ya.ru |
| 3 | Oleg | oleg@mail.ru |
| 4 | Nikolay | nikolay@example.com |
Давайте теперь обновим оставшихся пользователей, у которых почта на домене `example.com`. Для этого нам потребуется
метод [UpdateMany](../class_desc/classes/Database.md#82-обновление-нескольких-записей-updatemany):
```php
// Давайте сперва получим Ivan
$userIvan = $db->GetRow('users', where: new ConditionBuilder()->WhereEquals('user_name', 'Ivan'), className: "\\App\\Models\\User");
// Давайте сперва получим Nikolay
$userNikolay = $db->GetRow('users', where: new ConditionBuilder()->WhereEquals('user_name', 'Nikolay'), className: "\\App\\Models\\User");
// Меняем их почту
$userIvan->Email = "ivan@yandex.ru";
$userNikolay->Email = "nikolay@yandex.ru";
// Обновляем
if ($db->UpdateMany('users', $userIvan, $userNikolay))
echo 'Почты обновлены!';
```
Теперь таблица в БД имеет вид:
| id | user_name | user_mail |
|:--:|:---------:|:-----------------:|
| 1 | Ivan | ivan@yandex.ru |
| 2 | Olga | olga@ya.ru |
| 3 | Oleg | oleg@mail.ru |
| 4 | Nikolay | nikolay@yandex.ru |
Итак, мы рассмотрели все возможные способы обновления данных.
[Предыдущий пункт](count_exist_data.md) | [На главную](../index.md) | [Следующий пункт](delete_data.md)

190
help/class_desc/classes/ConditionBuilder.md
View File

@ -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 лет и они зарегистрированы позже

4
help/class_desc/classes/Database.md
View File

@ -213,8 +213,8 @@ $db = new Database($config, function(Exception $e, bool $terminate) {
**Параметры**
- `$table`: Имя таблицы.
- `$where`: Условие выбора (объект `ConditionBuilder`).
- `$columns`: Нужные столбцы (массив).
- `$where`: Условие выбора (объект `ConditionBuilder`).
- `$className`: Полное имя класса, реализующего интерфейс `IDBItem`.
**Возвращаемое значение:** Массив экземпляров указанных классов или false.
@ -267,7 +267,7 @@ $db = new Database($config, function(Exception $e, bool $terminate) {
**Возвращаемое значение:** true, если хотя бы одна запись найдена, иначе false.
### 8. Обновления и удаление
### 8. Обновление записей
#### 8.1. Обновление одной записи (`Update()`)

4
help/index.md
View File

@ -12,6 +12,10 @@
2. [x] [Создание таблицы](basic_usage/create_table.md)
3. [x] [Вставка данных](basic_usage/insert_data.md)
4. [x] [Получение данных](basic_usage/get_data.md)
5. [x] [Пороверка существования данных и их количество](basic_usage/count_exist_data.md)
6. [x] [Обновление данных](basic_usage/update_data.md)
7. [x] [Удаление данных](basic_usage/delete_data.md)
8. [x] [Удаление таблицы](basic_usage/drop_table.md)
## Описание интерфейсов, классов и перечислений:

17
sources/traits/ConditionBuilder/ConditionBuilderConditionsSet.php
View File

@ -93,16 +93,29 @@
return $this->AddCondition($column, '<=', $value);
}
/**
* Добавляет условие LIKE.
*
* @param string $column Имя колонки.
* @param string $value Значение.
*
* @return ConditionBuilder Возвращает объект для цепочек.
*/
public function WhereLike (string $column, string $value): ConditionBuilder
{
return $this->AddCondition($column, 'LIKE', $value);
}
/**
* Добавляет условие.
*
* @param string $column Имя колонки.
* @param string $operator Оператор (<=, <, =, >, >=).
* @param string $operator Оператор (<=, <, =, >, >=, ...).
* @param mixed $value Значение.
*
* @return ConditionBuilder Возвращает объект для цепочек.
*/
private function AddCondition (string $column, string $operator, mixed $value): ConditionBuilder
public function AddCondition (string $column, string $operator, mixed $value): ConditionBuilder
{
return $this->AddConditionA(new Condition($column, $operator, $value));
}

6
sources/traits/Database/DatabaseGet.php
View File

@ -67,14 +67,14 @@
* Получает набор строк в массиве данных, удовлетворяющий выборке.
*
* @param string $table Имя таблицы.
* @param ConditionBuilder $where Where-условия выборки.
* @param array $columns Колонки, которые нужно включить в запрос.
* @param ConditionBuilder $where Where-условия выборки.
* @param string $className Полное имя класса, реализуемого интерфейсом IDBItem.
*
* @return false|ObjectArray Массив найденных классов или <code>false</code> в случае ошибки.
*/
public
function GetRows (string $table, ConditionBuilder $where, array $columns = [],
function GetRows (string $table, array $columns = [], ConditionBuilder $where = new ConditionBuilder(),
string $className = "\\StdClass"): false|ObjectArray
{
// Задаю массив параметров
@ -124,7 +124,7 @@
* @see Query
*/
public
function GetCol (string $table, string $column, ConditionBuilder $where): false|array
function GetCol (string $table, string $column, ConditionBuilder $where = new ConditionBuilder()): false|array
{
/**
* Интерпретирую условия.