492 lines
20 KiB
Markdown
492 lines
20 KiB
Markdown
# Класс `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) |