# Класс `Database`

## Описание

Класс предназначен для взаимодействия с базами данных посредством библиотеки **PDO**. Данный класс предоставляет методы
для различных операций с базой данных, включая выполнение запросов, управление транзакциями, получение данных и
модификацию таблиц.

## Пространство имен

```php
namespace goodboyalex\php_db_components_pack\classes;
```

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

**Автор:** Александр Бабаев  
**Версия:** 1.0  
**Последнее обновление:** 1.0.1

## Основные возможности

### Создание и удаление класса

* **Конструктор (`__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. Транзакции

#### 3.1. Создание транзакции (`InitTransaction()`)

Начинает новую транзакцию в базе данных.

**Возвращаемое значение:** void.

#### 3.2. Проверка существования транзакции (`InTransaction()`)

Проверяет, активна ли транзакция.

**Возвращаемое значение:** true — транзакция активна, false — неактивна.

#### 3.3. Фиксация транзакций (`Commit()`)

Фиксирует выполненную транзакцию.

**Возвращаемое значение:** void.

#### 3.4. Откат транзакций (`RollBack()`)

Отменяет активные изменения транзакции.

**Возвращаемое значение:** void.

### 4. Выполнение запросов

#### 4.1. Произвольный запрос (`Query()`)

Выполняет произвольный SQL-запрос и возвращает результат в виде массива.

**Параметры**

- `$query`: Строка с SQL-запросом.
- `$params`: Массив параметров для подготовки запроса.

**Возвращаемое значение:** Ассоциативный массив или false в случае ошибки.

#### 4.2. Первая строка запроса (`QueryFirst()`)

Получает первую строку результата запроса.

**Возвращаемое значение:** Ассоциативный массив первой строки или false.

#### 4.3. Последняя строка запроса (`QueryLast()`)

Получает последнюю строку результата запроса.

**Возвращаемое значение:** Ассоциативный массив последней строки или false.

#### 4.4. Изменяющие запросы (`Execute()`)

Выполняет запросы модификации данных (INSERT, UPDATE, DELETE).

**Возвращаемое значение:** Число затронутых строк или false.

### 5. Вставка данных

#### 5.1. Одинарная вставка (`Insert()`)

Вставляет один объект в базу данных.

**Параметры**

- `$table`: Имя целевой таблицы.
- `$row`: Объект, реализующий интерфейс `IDBItem`.

**Возвращаемое значение:** Идентификатор созданной записи, -1 или false в случае ошибки.

#### 5.2. Массовая вставка (`InsertMany()`)

Вставляет несколько объектов одновременно.

**Параметры**

- `$table`: Имя целевой таблицы.
- `...$sources`: Список объектов, реализующих интерфейс `IDBItem`.

**Возвращаемое значение:** Массив идентификаторов новых записей или false.

### 6. Получение данных

#### 6.1. Получение одного объекта (`GetRow()`)

Получает одну запись из базы данных и создаёт экземпляр указанного класса.

**Параметры**

- `$table`: Имя таблицы.
- `$columns`: Необходимые колонки (массив).
- `$where`: Условие выбора (объект `ConditionBuilder`).
- `$className`: Полное имя класса, реализующего интерфейс `IDBItem`.

**Возвращаемое значение:** Экземпляр указанного класса (реализующего интерфейс IDBItem) или false.

#### 6.2. Получение набора объектов (`GetRows()`)

Получает список объектов из базы данных.

**Параметры**

- `$table`: Имя таблицы.
- `$columns`: Нужные столбцы (массив).
- `$where`: Условие выбора (объект `ConditionBuilder`).
- `$className`: Полное имя класса, реализующего интерфейс `IDBItem`.

**Возвращаемое значение:** Массив экземпляров указанных классов или false.

#### 6.3. Получение столбца (`GetCol()`)

Выбирает конкретные столбцы и возвращает их в виде массива.

**Параметры**

- `$table`: Имя таблицы.
- `$column`: Выбираемый столбец.
- `$where`: Условия выборки (объект `ConditionBuilder`).

**Возвращаемое значение:** Массив значений столбца или false.

#### 6.4. Получение одиночного значения (`GetValue()`)

Выборка единственного значения (поле).

**Параметры**

- `$table`: Имя таблицы.
- `$column`: Столбец, содержащий искомое значение.
- `$where`: Условия выборки (объект `ConditionBuilder`).

**Возвращаемое значение:** Значение выбранного поля или null.

### 7. Подсчёт количества / существование записи

#### 7.1. Подсчет записей (`Count()`)

Подсчитывает количество записей, соответствующих фильтру.

**Параметры**

- `$table`: Имя таблицы.
- `$where`: Условия подсчета (объект `ConditionBuilder`).

**Возвращаемое значение:** Целочисленное значение числа записей или -1 в случае ошибки.

#### 7.2. Проверка существования записей (`IsExist()`)

Проверяет наличие хотя бы одной записи по указанным критериям.

**Параметры**

- `$table`: Имя таблицы.
- `$where`: Условия фильтра (объект `ConditionBuilder`).

**Возвращаемое значение:** true, если хотя бы одна запись найдена, иначе false.

### 8. Обновление записей

#### 8.1. Обновление одной записи (`Update()`)

Обновляет одно значение в таблице.

**Параметры**

- `$table`: Имя таблицы.
- `$item`: Объект, реализующий интерфейс `IDBItem`.

**Возвращаемое значение:** true при успешном выполнении, false — в противном случае.

#### 8.2. Обновление нескольких записей (`UpdateMany()`)

Массовое обновление записей.

**Параметры**

- `$table`: Имя таблицы.
- `...$items`: Множество объектов, реализующих интерфейс `IDBItem`.

**Возвращаемое значение:** true при успешной массовой обработке, false — в случае ошибки.

### 9. Удаление записей (`Delete()`)

Удаляет записи по заданному критерию.

**Параметры**

- `$table`: Имя таблицы.
- `$where`: Критерии удаления (объект `ConditionBuilder`).

**Возвращаемое значение:** true при успехе, false — в случае ошибки.

### 10. Управление таблицами

#### 10.1. Проверка существования таблицы (`IsTableExist()`)

Проверяет существование конкретной таблицы.

**Параметр**

- `$tableName`: Имя проверяемой таблицы.

**Возвращаемое значение:** true, если таблица существует, false — если отсутствует.

#### 10.2. Создание таблицы (`CreateTable()`)

Создает новую таблицу на основе структуры модели.

**Параметры**

- `$tableName`: Имя создаваемой таблицы.
- `$dbItemClass`: Класс модели, представляющий структуру таблицы.

**Возвращаемое значение:** true при создании, false — в случае неудачи.

#### 10.3. Удаление таблицы (`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->Username = 'test_user';
$userData->Email = 'test@example.com';
$result = $db->Insert($table, $userData);
if ($result !== false)
    echo "Пользователь успешно добавлен!";
```

#### Пример №2: обновление данных:

```php
// Допустим, мы хотим обновить email пользователя
$newEmail = 'new_email@example.com';

// $userData - это UserModel (полученная ранее из БД)

// Обновим Email
$userData->Email = $newEmail;

if ($db->Update('users', $userData))
    echo "Данные пользователя успешно обновлены.";
```

### Пример №3: Массовая вставка данных

Допустим, вам нужно добавить несколько пользователей одним запросом:

```php
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()->WhereEquals('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()->WhereGreaterThan('age', 30);

// Загружаем всех пользователей, соответствующих условию
$users = $db->GetRows('users', $condition, ['id', 'username'], '\\UserModel');

foreach ($users as $user) {
    echo "Имя пользователя: {$user->Name()}, возраст: {$user->Age}\n";
}
```

### Пример №6: Подсчет общего количества зарегистрированных пользователей

Нужно посчитать общее число пользователей в базе данных:

```php
use goodboyalex\php_db_components_pack\conditions\ConditionBuilder;

// Используем пустое условие, чтобы считать всех пользователей
$condition = new ConditionBuilder();

// Подсчет количества пользователей
$count = $db->Count('users');

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()->WhereLessThanEqual('last_login_date', $lastMonthDate);

// Удаляем старых пользователей
if ($db->Delete('users', $condition))
    echo "Устаревшие пользователи были успешно удалены.\n";
else
    echo "Ошибка при удалении устаревших пользователей.\n";
```

Эти примеры демонстрируют широкий спектр возможностей, предоставляемых классом `Database`, позволяя эффективно управлять
взаимодействием с базой данных.

## Вывод

Таким образом, этот класс предоставляет удобные инструменты для реализации большинства стандартных операций с базой
данных на уровне ORM-подхода.

[На главную](../../index.md)