20250805-1

2025-08-05 22:26:43 +03:00
parent 3161fcf4dd
commit 7b42ba781c
14 changed files with 496 additions and 17 deletions
--- a/help/class_desc/classes/Database.md
+++ b/help/class_desc/classes/Database.md
@@ -0,0 +1,492 @@
+# Класс `Database`
+
+## Описание
+
+Класс предназначен для взаимодействия с базами данных посредством библиотеки **PDO**. Данный класс предоставляет методы
+для различных операций с базой данных, включая выполнение запросов, управление транзакциями, получение данных и
+модификацию таблиц.
+
+## Пространство имен
+
+```php
+namespace goodboyalex\php_db_components_pack\classes;
+```
+
+## Автор и версия
+
+**Автор:** Александр Бабаев  
+**Версия:** 1.0  
+**Последнее обновление:** 1.0
+
+## Основные возможности
+
+### Создание и удаление класса
+
+* **Конструктор (`__construct`)**: Устанавливает подключение к базе данных и принимает анонимную функцию обработки
+  исключений.
+* **Деструктор (`__destruct`)**: Завершает работу соединения с базой данных.
+
+### Управление транзакциями
+
+* `InitTransaction()`: Начало новой транзакции.
+* `InTransaction()`: Проверка статуса активной транзакции.
+* `Commit()`: Фиксация изменений в базе данных.
+* `RollBack()`: Отмена изменений в рамках текущей транзакции.
+
+### Выполнение запросов
+
+* `Query($query, $params)`: Выполняет произвольный SQL-запрос и возвращает ассоциативный массив результатов.
+* `QueryFirst($query, $params)`: Возвращает первую строку результата запроса.
+* `QueryLast($query, $params)`: Возвращает последнюю строку результата запроса.
+* `Execute($query, $params)`: Выполняет запрос изменения данных (например, INSERT/UPDATE/DELETE).
+
+### Вставка
+
+* `Insert($table, $row)`: Добавление одной записи в указанную таблицу.
+* `InsertMany($table, ...$sources)`: Массовая вставка нескольких записей одновременно.
+
+### Получение
+
+* `GetRow($table, $where, $columns, $className)`: Выборка одной записи и создание соответствующего объекта модели.
+* `GetRows($table, $where, $columns, $className)`: Выборка множества записей и преобразование их в объекты модели.
+* `GetCol ($table, $column, $where)`: Выборка столбца.
+* `GetValue ($table, $column, $where)`: Выборка конкретной ячейки таблицы.
+
+### Обновление
+
+* `Update($table, $item)`: Обновление одной записи в указанной таблице.
+* `UpdateMany($table, ...$items)`: Обновление сразу нескольких записей.
+
+### Удаление
+
+* `Delete($table, $where)`: Удаление записей по заданному условию.
+
+### Подсчёт количества / существование записи
+
+* **`Count($table, $where)`**: Подсчет количества записей, соответствующих условиям.
+* **`IsExist($table, $where)`**: Проверка существования хотя бы одной записи по указанному условию.
+
+### Управление таблицами
+
+* **`CreateTable($tableName, $dbItemClass)`**: Создание новой таблицы на основе описания класса модели.
+* **`DropTable($tableName)`**: Удаление существующей таблицы.
+* **`IsTableExist($tableName)`**: Проверка наличия таблицы в базе данных.
+
+---
+
+## Методы подробно
+
+### 1. Конструктор (`__construct`)
+
+Создает новое подключение к базе данных и устанавливает обработчик исключений.
+
+**Параметры**
+
+- `$config`: Объект конфигурации подключения типа `DBConfig`.
+- `$onException`: Функция обратного вызова для обработки исключений. Принимается анонимная функция формата:
+  `function (Exception $e, bool $isTerminate): void`, где `$e` - исключение, `$isTerminate` - требуется ли прерывание
+  выполнения или это исключение нужно просто показать (или занести в журнал).
+
+**Пример использования**
+
+```php
+$config = new DBConfig('mysql', 'localhost', 'database_name', 'username', 'password');
+$db = new Database($config, function(Exception $e, bool $terminate) {
+    // Создаём текст ошибки
+    $message = "Ошибка: {$e->getMessage()}";
+    // Если смертельная
+    if ($terminate)
+        // - то убиваю скрипт
+        die($message);
+    else
+        // - нет? Просто выведу сообщение
+        echo $message;
+});
+```
+
+### 2. Деструктор (`__destruct`)
+
+Закрывает активное соединение с базой данных.
+
+**Возвращаемое значение:** Нет возвращаемого значения.
+
+### 3. Транзакции
+
+#### Создание транзакции (`InitTransaction()`)
+
+Начинает новую транзакцию в базе данных.
+
+**Возвращаемое значение:** void.
+
+#### Проверка существования транзакции (`InTransaction()`)
+
+Проверяет, активна ли транзакция.
+
+**Возвращаемое значение:** true — транзакция активна, false — неактивна.
+
+#### Фиксация транзакций (`Commit()`)
+
+Фиксирует выполненную транзакцию.
+
+**Возвращаемое значение:** void.
+
+#### Откат транзакций (`RollBack()`)
+
+Отменяет активные изменения транзакции.
+
+**Возвращаемое значение:** void.
+
+### 4. Выполнение запросов
+
+#### Произвольный запрос (`Query()`)
+
+Выполняет произвольный SQL-запрос и возвращает результат в виде массива.
+
+**Параметры**
+
+- `$query`: Строка с SQL-запросом.
+- `$params`: Массив параметров для подготовки запроса.
+
+**Возвращаемое значение:** Ассоциативный массив или false в случае ошибки.
+
+#### Первая строка запроса (`QueryFirst()`)
+
+Получает первую строку результата запроса.
+
+**Возвращаемое значение:** Ассоциативный массив первой строки или false.
+
+#### Последняя строка запроса (`QueryLast()`)
+
+Получает последнюю строку результата запроса.
+
+**Возвращаемое значение:** Ассоциативный массив последней строки или false.
+
+#### Изменяющие запросы (`Execute()`)
+
+Выполняет запросы модификации данных (INSERT, UPDATE, DELETE).
+
+**Возвращаемое значение:** Число затронутых строк или false.
+
+### 5. Вставка данных
+
+#### Одинарная вставка (`Insert()`)
+
+Вставляет один объект в базу данных.
+
+**Параметры**
+
+- `$table`: Имя целевой таблицы.
+- `$row`: Объект, реализующий интерфейс `IDBItem`.
+
+**Возвращаемое значение:** Идентификатор созданной записи, -1 или false в случае ошибки.
+
+#### Массовая вставка (`InsertMany()`)
+
+Вставляет несколько объектов одновременно.
+
+**Параметры**
+
+- `$table`: Имя целевой таблицы.
+- `...$sources`: Список объектов, реализующих интерфейс `IDBItem`.
+
+**Возвращаемое значение:** Массив идентификаторов новых записей или false.
+
+### 6. Получение данных
+
+#### Получение одного объекта (`GetRow()`)
+
+Получает одну запись из базы данных и создаёт экземпляр указанного класса.
+
+**Параметры**
+
+- `$table`: Имя таблицы.
+- `$where`: Условие выбора (объект `ConditionBuilder`).
+- `$columns`: Необходимые колонки (массив).
+- `$className`: Полное имя класса, реализующего интерфейс `IDBItem`.
+
+**Возвращаемое значение:** Экземпляр указанного класса или false.
+
+#### Получение набора объектов (`GetRows()`)
+
+Получает список объектов из базы данных.
+
+**Параметры**
+
+- `$table`: Имя таблицы.
+- `$where`: Условие выбора (объект `ConditionBuilder`).
+- `$columns`: Нужные столбцы (массив).
+- `$className`: Полное имя класса, реализующего интерфейс `IDBItem`.
+
+**Возвращаемое значение:** Массив экземпляров указанных классов или false.
+
+#### Получение столбца (`GetCol()`)
+
+Выбирает конкретные столбцы и возвращает их в виде массива.
+
+**Параметры**
+
+- `$table`: Имя таблицы.
+- `$column`: Выбираемый столбец.
+- `$where`: Условия выборки (объект `ConditionBuilder`).
+
+**Возвращаемое значение:** Массив значений столбца или false.
+
+#### Получение одиночного значения (`GetValue()`)
+
+Выборка единственного значения (поле).
+
+**Параметры**
+
+- `$table`: Имя таблицы.
+- `$column`: Столбец, содержащий искомое значение.
+- `$where`: Условия выборки (объект `ConditionBuilder`).
+
+**Возвращаемое значение:** Значение выбранного поля или null.
+
+### 7. Подсчёт количества / существование записи
+
+#### Подсчет записей (`Count()`)
+
+Подсчитывает количество записей, соответствующих фильтру.
+
+**Параметры**
+
+- `$table`: Имя таблицы.
+- `$where`: Условия подсчета (объект `ConditionBuilder`).
+
+**Возвращаемое значение:** Целочисленное значение числа записей или -1 в случае ошибки.
+
+#### Проверка существования записей (`IsExist()`)
+
+Проверяет наличие хотя бы одной записи по указанным критериям.
+
+**Параметры**
+
+- `$table`: Имя таблицы.
+- `$where`: Условия фильтра (объект `ConditionBuilder`).
+
+**Возвращаемое значение:** true, если хотя бы одна запись найдена, иначе false.
+
+### 8. Обновления и удаление
+
+#### Обновление одной записи (`Update()`)
+
+Обновляет одно значение в таблице.
+
+**Параметры**
+
+- `$table`: Имя таблицы.
+- `$item`: Объект, реализующий интерфейс `IDBItem`.
+
+**Возвращаемое значение:** true при успешном выполнении, false — в противном случае.
+
+#### Обновление нескольких записей (`UpdateMany()`)
+
+Массовое обновление записей.
+
+**Параметры**
+
+- `$table`: Имя таблицы.
+- `...$items`: Множество объектов, реализующих интерфейс `IDBItem`.
+
+**Возвращаемое значение:** true при успешной массовой обработке, false — в случае ошибки.
+
+#### Удаление записей (`Delete()`)
+
+Удаляет записи по заданному критерию.
+
+**Параметры**
+
+- `$table`: Имя таблицы.
+- `$where`: Критерии удаления (объект `ConditionBuilder`).
+
+**Возвращаемое значение:** true при успехе, false — в случае ошибки.
+
+### 9. Управление таблицами
+
+#### Проверка существования таблицы (`IsTableExist()`)
+
+Проверяет существование конкретной таблицы.
+
+**Параметр**
+
+- `$tableName`: Имя проверяемой таблицы.
+
+**Возвращаемое значение:** true, если таблица существует, false — если отсутствует.
+
+#### Создание таблицы (`CreateTable()`)
+
+Создает новую таблицу на основе структуры модели.
+
+**Параметры**
+
+- `$tableName`: Имя создаваемой таблицы.
+- `$dbItemClass`: Класс модели, представляющий структуру таблицы.
+
+**Возвращаемое значение:** true при создании, false — в случае неудачи.
+
+#### Удаление таблицы (`DropTable()`)
+
+Удаляет таблицу из базы данных.
+
+**Параметр**
+
+- `$tableName`: Имя удаляемой таблицы.
+
+**Возвращаемое значение:** true при удачном удалении, false — в случае ошибки.
+
+---
+
+### Примеры использования методов
+
+#### Пример №1: добавления новой записи:
+
+Предположим для примеров, что есть некоторый класс пользователя
+
+```php
+use goodboyalex\php_db_components_pack\interfaces\IDBItem;
+
+class UserModel implements IDBItem {
+...    
+}
+```
+Добавим его в базу данных:
+
+```php
+$table = 'users';
+$userData = new UserModel();
+$userData->setUsername('test_user')->setEmail('test@example.com');
+$result = $db->Insert($table, $userData);
+if ($result !== false) {
+    echo "Пользователь успешно добавлен!";
+}
+```
+
+#### Пример №2: обновление данных:
+
+```php
+// Допустим, мы хотим обновить email пользователя
+$newEmail = 'new_email@example.com';
+
+// $userData - это UserModel (полученная ранее из БД)
+
+// Обновим Email
+$userData->setEmail($newEmail);
+
+if ($db->Update('users', $userData)) {
+    echo "Данные пользователя успешно обновлены.";
+}
+```
+
+### Пример №3: Массовая вставка данных
+
+Допустим, вам нужно добавить несколько пользователей одним запросом:
+
+```php
+use goodboyalex\php_db_components_pack\classes\Database;
+use goodboyalex\php_db_components_pack\models\UserModel;
+
+// Предположим, что у вас уже инициализирован объект $db
+$table = 'users';
+
+// Массив объектов пользователей
+$sources[] = new UserModel(['username' => 'Alice']);
+$sources[] = new UserModel(['username' => 'Bob']);
+
+// Вставляем всех пользователей разом
+$result = $db->InsertMany($table, ...$sources);
+
+if ($result !== false) {
+    foreach ($result as $insertedId) {
+        echo "Добавлен новый пользователь с ID: $insertedId\n";
+    }
+} else {
+    echo "Ошибка при массовом добавлении пользователей.\n";
+}
+```
+
+### Пример №4: Проверка существования пользователя по имени
+
+Вам нужно проверить, зарегистрирован ли пользователь с определенным именем в вашей базе данных:
+
+```php
+use goodboyalex\php_db_components_pack\conditions\ConditionBuilder;
+
+// Настраиваем условие
+$condition = new ConditionBuilder();
+$condition->addCondition('username', '=', 'JohnDoe');
+
+// Проверяем наличие пользователя
+$exists = $db->IsExist('users', $condition);
+
+if ($exists) {
+    echo "Пользователь JohnDoe уже зарегистрирован!\n";
+} else {
+    echo "Пользователь JohnDoe пока не зарегистрирован.\n";
+}
+```
+
+### Пример №5: Поиск списка пользователей старше определенного возраста
+
+Допустим, нам нужно выбрать всех пользователей старше 30 лет:
+
+```php
+use goodboyalex\php_db_components_pack\conditions\ConditionBuilder;
+
+// Настройка условия
+$condition = new ConditionBuilder();
+$condition->addCondition('age', '>=', 30);
+
+// Загружаем всех пользователей, соответствующих условию
+$users = $db->GetRows('users', $condition, ['id', 'username'], '\\UserModel');
+
+foreach ($users as $user) {
+    echo "Имя пользователя: {$user->getUsername()}, возраст: {$user->getAge()}\n";
+}
+```
+
+### Пример №6: Подсчет общего количества зарегистрированных пользователей
+
+Нужно посчитать общее число пользователей в базе данных:
+
+```php
+use goodboyalex\php_db_components_pack\conditions\ConditionBuilder;
+
+// Используем пустое условие, чтобы считать всех пользователей
+$condition = new ConditionBuilder();
+
+// Подсчет количества пользователей
+$count = $db->Count('users', $condition);
+
+echo "Всего зарегистрировано пользователей: $count\n";
+```
+
+### Пример №7: Удаление устаревших пользователей
+
+Например, вы хотите удалить всех пользователей, чья активность была давно утрачена (предположим, пользователи с датой последнего входа больше месяца назад):
+
+```php
+use goodboyalex\php_db_components_pack\conditions\ConditionBuilder;
+
+// Например, удаляем пользователей, не заходивших последний месяц
+$lastMonthDate = date("Y-m-d H:i:s", strtotime('-1 month'));
+
+$condition = new ConditionBuilder();
+$condition->addCondition('last_login_date', '<=', $lastMonthDate);
+
+// Удаляем старых пользователей
+if ($db->Delete('users', $condition)) {
+    echo "Устаревшие пользователи были успешно удалены.\n";
+} else {
+    echo "Ошибка при удалении устаревших пользователей.\n";
+}
+```
+
+Эти примеры демонстрируют широкий спектр возможностей, предоставляемых классом `Database`, позволяя эффективно управлять взаимодействием с базой данных.
+
+## Вывод
+
+Таким образом, этот класс предоставляет удобные инструменты для реализации большинства стандартных операций с базой
+данных на уровне ORM-подхода.
+
+[На главную](../../index.md)
--- a/help/class_desc/classes/tm_drivers/MSSQLTableManager.md
+++ b/help/class_desc/classes/tm_drivers/MSSQLTableManager.md
@@ -0,0 +1,24 @@
+# Класс `MSSQLTableManager`
+
+Класс `MSSQLTableManager` реализует интерфейс `ITableManager` и предназначен для работы с системой управления базами
+данных Microsoft SQL Server (MS SQL). Он предоставляет функциональность для создания таблиц, проверки их существования и
+формирования SQL-запросов.
+
+## Пространство имён
+
+```php
+namespace goodboyalex\php_db_components_pack\classes\tm_drivers;
+```
+
+## Автор и версия
+
+- **Автор**: Александр Бабаев
+- **Версия**: 1.0
+- **Дата выпуска**: с версии 1.0
+
+## Важные моменты
+
+Данный класс является внутренним классом для реализации классом [Database](../Database.md) таких методов как:
+проверка существования и создания таблицы базы данных.
+
+[На главную](../../../index.md)
--- a/help/class_desc/classes/tm_drivers/MySQLTableManager.md
+++ b/help/class_desc/classes/tm_drivers/MySQLTableManager.md
@@ -0,0 +1,24 @@
+# Класс `MySQLTableManager`
+
+Класс `MySQLTableManager` реализует интерфейс `ITableManager` и предназначен для работы с системой управления базами
+данных Microsoft SQL Server (MS SQL). Он предоставляет функциональность для создания таблиц, проверки их существования и
+формирования SQL-запросов.
+
+## Пространство имён
+
+```php
+namespace goodboyalex\php_db_components_pack\classes\tm_drivers;
+```
+
+## Автор и версия
+
+- **Автор**: Александр Бабаев
+- **Версия**: 1.0
+- **Дата выпуска**: с версии 1.0
+
+## Важные моменты
+
+Данный класс является внутренним классом для реализации классом [Database](../Database.md) таких методов как:
+проверка существования и создания таблицы базы данных.
+
+[На главную](../../../index.md)
--- a/help/class_desc/classes/tm_drivers/OracleDBTableManager.md
+++ b/help/class_desc/classes/tm_drivers/OracleDBTableManager.md
@@ -0,0 +1,24 @@
+# Класс `OracleDBTableManager`
+
+Класс `OracleDBTableManager` реализует интерфейс `ITableManager` и предназначен для работы с системой управления базами
+данных Microsoft SQL Server (MS SQL). Он предоставляет функциональность для создания таблиц, проверки их существования и
+формирования SQL-запросов.
+
+## Пространство имён
+
+```php
+namespace goodboyalex\php_db_components_pack\classes\tm_drivers;
+```
+
+## Автор и версия
+
+- **Автор**: Александр Бабаев
+- **Версия**: 1.0
+- **Дата выпуска**: с версии 1.0
+
+## Важные моменты
+
+Данный класс является внутренним классом для реализации классом [Database](../Database.md) таких методов как:
+проверка существования и создания таблицы базы данных.
+
+[На главную](../../../index.md)
--- a/help/class_desc/classes/tm_drivers/PostgreSQLTableManager.md
+++ b/help/class_desc/classes/tm_drivers/PostgreSQLTableManager.md
@@ -0,0 +1,24 @@
+# Класс `PostgreSQLTableManager`
+
+Класс `PostgreSQLTableManager` реализует интерфейс `ITableManager` и предназначен для работы с системой управления базами
+данных Microsoft SQL Server (MS SQL). Он предоставляет функциональность для создания таблиц, проверки их существования и
+формирования SQL-запросов.
+
+## Пространство имён
+
+```php
+namespace goodboyalex\php_db_components_pack\classes\tm_drivers;
+```
+
+## Автор и версия
+
+- **Автор**: Александр Бабаев
+- **Версия**: 1.0
+- **Дата выпуска**: с версии 1.0
+
+## Важные моменты
+
+Данный класс является внутренним классом для реализации классом [Database](../Database.md) таких методов как:
+проверка существования и создания таблицы базы данных.
+
+[На главную](../../../index.md)
--- a/help/class_desc/classes/tm_drivers/SQLiteTableManager.md
+++ b/help/class_desc/classes/tm_drivers/SQLiteTableManager.md
@@ -0,0 +1,24 @@
+# Класс `SQLiteTableManager`
+
+Класс `SQLiteTableManager` реализует интерфейс `ITableManager` и предназначен для работы с системой управления базами
+данных Microsoft SQL Server (MS SQL). Он предоставляет функциональность для создания таблиц, проверки их существования и
+формирования SQL-запросов.
+
+## Пространство имён
+
+```php
+namespace goodboyalex\php_db_components_pack\classes\tm_drivers;
+```
+
+## Автор и версия
+
+- **Автор**: Александр Бабаев
+- **Версия**: 1.0
+- **Дата выпуска**: с версии 1.0
+
+## Важные моменты
+
+Данный класс является внутренним классом для реализации классом [Database](../Database.md) таких методов как:
+проверка существования и создания таблицы базы данных.
+
+[На главную](../../../index.md)