babaev-an/php_db_components_pack
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
php_db_components_pack/help/class_desc/classes/Database.md
babaev-an 3dc403ebf2 20250810 v1.0
2025-08-10 11:48:29 +03:00

20 KiB
Raw Permalink Blame History

Класс Database

Описание

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

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

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 - требуется ли прерывание выполнения или это исключение нужно просто показать (или занести в журнал).

Пример использования

$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.

Возвращаемое значение: Экземпляр указанного класса или 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: добавления новой записи:

Предположим для примеров, что есть некоторый класс пользователя

use goodboyalex\php_db_components_pack\interfaces\IDBItem;

class UserModel implements IDBItem {
...    
}

Добавим его в базу данных:

$table = 'users';
$userData = new UserModel();
$userData->Username = 'test_user';
$userData->Email = 'test@example.com';
$result = $db->Insert($table, $userData);
if ($result !== false)
    echo "Пользователь успешно добавлен!";

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

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

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

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

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

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

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

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: Проверка существования пользователя по имени

Вам нужно проверить, зарегистрирован ли пользователь с определенным именем в вашей базе данных:

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 лет:

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: Подсчет общего количества зарегистрированных пользователей

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

use goodboyalex\php_db_components_pack\conditions\ConditionBuilder;

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

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

echo "Всего зарегистрировано пользователей: $count\n";

Пример №7: Удаление устаревших пользователей

Например, вы хотите удалить всех пользователей, чья активность была давно утрачена (предположим, пользователи с датой последнего входа больше месяца назад):

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-подхода.

На главную