From 819a305fded3550608434703d57929fffc3d0d61 Mon Sep 17 00:00:00 2001 From: babaev-an Date: Thu, 7 Aug 2025 21:40:01 +0300 Subject: [PATCH] 20250807 --- help/basic_usage/usage_preparation.md | 12 ++- help/class_desc/classes/Database.md | 98 +++++++++---------- help/index.md | 20 ++++ .../traits/Database/DatabaseCountExist.php | 2 +- sources/traits/Database/DatabaseDelete.php | 2 +- sources/traits/Database/DatabaseGet.php | 13 ++- sources/traits/Database/DatabaseUpdate.php | 8 +- 7 files changed, 91 insertions(+), 64 deletions(-) diff --git a/help/basic_usage/usage_preparation.md b/help/basic_usage/usage_preparation.md index d8b3883..2ca0ddd 100644 --- a/help/basic_usage/usage_preparation.md +++ b/help/basic_usage/usage_preparation.md @@ -18,7 +18,17 @@ $db_config = new DBConfig( Первым параметром идёт драйвер СУБД, представленный перечислением [DBDriver](../class_desc/enums/DBDriver.md), затем сервер БД, порт, её имя, пользователь, пароль и ключ для шифрования (_если используете действия интерфейса ISerializable_). -Итак, настройки созданы, время создать сам класс [Database](../class_desc/classes/Database.md) +Итак, настройки созданы, время создать сам класс [Database](../class_desc/classes/Database.md): + +```php +use goodboyalex\php_db_components_pack\classes\Database; + +$onException = fn (Exception $exception, bool $terminate) => $terminate + ? die($exception->getMessage()) + : echo $exception->getMessage(); + +$db = new Database($db_config, $onException); +``` [На главную](../index.md) | [Следующий пункт](../index.md) \ No newline at end of file diff --git a/help/class_desc/classes/Database.md b/help/class_desc/classes/Database.md index 5591866..5e9fc70 100644 --- a/help/class_desc/classes/Database.md +++ b/help/class_desc/classes/Database.md @@ -112,25 +112,25 @@ $db = new Database($config, function(Exception $e, bool $terminate) { ### 3. Транзакции -#### Создание транзакции (`InitTransaction()`) +#### 3.1. Создание транзакции (`InitTransaction()`) Начинает новую транзакцию в базе данных. **Возвращаемое значение:** void. -#### Проверка существования транзакции (`InTransaction()`) +#### 3.2. Проверка существования транзакции (`InTransaction()`) Проверяет, активна ли транзакция. **Возвращаемое значение:** true — транзакция активна, false — неактивна. -#### Фиксация транзакций (`Commit()`) +#### 3.3. Фиксация транзакций (`Commit()`) Фиксирует выполненную транзакцию. **Возвращаемое значение:** void. -#### Откат транзакций (`RollBack()`) +#### 3.4. Откат транзакций (`RollBack()`) Отменяет активные изменения транзакции. @@ -138,7 +138,7 @@ $db = new Database($config, function(Exception $e, bool $terminate) { ### 4. Выполнение запросов -#### Произвольный запрос (`Query()`) +#### 4.1. Произвольный запрос (`Query()`) Выполняет произвольный SQL-запрос и возвращает результат в виде массива. @@ -149,19 +149,19 @@ $db = new Database($config, function(Exception $e, bool $terminate) { **Возвращаемое значение:** Ассоциативный массив или false в случае ошибки. -#### Первая строка запроса (`QueryFirst()`) +#### 4.2. Первая строка запроса (`QueryFirst()`) Получает первую строку результата запроса. **Возвращаемое значение:** Ассоциативный массив первой строки или false. -#### Последняя строка запроса (`QueryLast()`) +#### 4.3. Последняя строка запроса (`QueryLast()`) Получает последнюю строку результата запроса. **Возвращаемое значение:** Ассоциативный массив последней строки или false. -#### Изменяющие запросы (`Execute()`) +#### 4.4. Изменяющие запросы (`Execute()`) Выполняет запросы модификации данных (INSERT, UPDATE, DELETE). @@ -169,7 +169,7 @@ $db = new Database($config, function(Exception $e, bool $terminate) { ### 5. Вставка данных -#### Одинарная вставка (`Insert()`) +#### 5.1. Одинарная вставка (`Insert()`) Вставляет один объект в базу данных. @@ -180,7 +180,7 @@ $db = new Database($config, function(Exception $e, bool $terminate) { **Возвращаемое значение:** Идентификатор созданной записи, -1 или false в случае ошибки. -#### Массовая вставка (`InsertMany()`) +#### 5.2. Массовая вставка (`InsertMany()`) Вставляет несколько объектов одновременно. @@ -193,20 +193,20 @@ $db = new Database($config, function(Exception $e, bool $terminate) { ### 6. Получение данных -#### Получение одного объекта (`GetRow()`) +#### 6.1. Получение одного объекта (`GetRow()`) Получает одну запись из базы данных и создаёт экземпляр указанного класса. **Параметры** - `$table`: Имя таблицы. -- `$where`: Условие выбора (объект `ConditionBuilder`). - `$columns`: Необходимые колонки (массив). +- `$where`: Условие выбора (объект `ConditionBuilder`). - `$className`: Полное имя класса, реализующего интерфейс `IDBItem`. **Возвращаемое значение:** Экземпляр указанного класса или false. -#### Получение набора объектов (`GetRows()`) +#### 6.2. Получение набора объектов (`GetRows()`) Получает список объектов из базы данных. @@ -219,7 +219,7 @@ $db = new Database($config, function(Exception $e, bool $terminate) { **Возвращаемое значение:** Массив экземпляров указанных классов или false. -#### Получение столбца (`GetCol()`) +#### 6.3. Получение столбца (`GetCol()`) Выбирает конкретные столбцы и возвращает их в виде массива. @@ -231,7 +231,7 @@ $db = new Database($config, function(Exception $e, bool $terminate) { **Возвращаемое значение:** Массив значений столбца или false. -#### Получение одиночного значения (`GetValue()`) +#### 6.4. Получение одиночного значения (`GetValue()`) Выборка единственного значения (поле). @@ -245,7 +245,7 @@ $db = new Database($config, function(Exception $e, bool $terminate) { ### 7. Подсчёт количества / существование записи -#### Подсчет записей (`Count()`) +#### 7.1. Подсчет записей (`Count()`) Подсчитывает количество записей, соответствующих фильтру. @@ -256,7 +256,7 @@ $db = new Database($config, function(Exception $e, bool $terminate) { **Возвращаемое значение:** Целочисленное значение числа записей или -1 в случае ошибки. -#### Проверка существования записей (`IsExist()`) +#### 7.2. Проверка существования записей (`IsExist()`) Проверяет наличие хотя бы одной записи по указанным критериям. @@ -269,7 +269,7 @@ $db = new Database($config, function(Exception $e, bool $terminate) { ### 8. Обновления и удаление -#### Обновление одной записи (`Update()`) +#### 8.1. Обновление одной записи (`Update()`) Обновляет одно значение в таблице. @@ -280,7 +280,7 @@ $db = new Database($config, function(Exception $e, bool $terminate) { **Возвращаемое значение:** true при успешном выполнении, false — в противном случае. -#### Обновление нескольких записей (`UpdateMany()`) +#### 8.2. Обновление нескольких записей (`UpdateMany()`) Массовое обновление записей. @@ -291,7 +291,7 @@ $db = new Database($config, function(Exception $e, bool $terminate) { **Возвращаемое значение:** true при успешной массовой обработке, false — в случае ошибки. -#### Удаление записей (`Delete()`) +### 9. Удаление записей (`Delete()`) Удаляет записи по заданному критерию. @@ -302,9 +302,9 @@ $db = new Database($config, function(Exception $e, bool $terminate) { **Возвращаемое значение:** true при успехе, false — в случае ошибки. -### 9. Управление таблицами +### 10. Управление таблицами -#### Проверка существования таблицы (`IsTableExist()`) +#### 10.1. Проверка существования таблицы (`IsTableExist()`) Проверяет существование конкретной таблицы. @@ -314,7 +314,7 @@ $db = new Database($config, function(Exception $e, bool $terminate) { **Возвращаемое значение:** true, если таблица существует, false — если отсутствует. -#### Создание таблицы (`CreateTable()`) +#### 10.2. Создание таблицы (`CreateTable()`) Создает новую таблицу на основе структуры модели. @@ -325,7 +325,7 @@ $db = new Database($config, function(Exception $e, bool $terminate) { **Возвращаемое значение:** true при создании, false — в случае неудачи. -#### Удаление таблицы (`DropTable()`) +#### 10.3. Удаление таблицы (`DropTable()`) Удаляет таблицу из базы данных. @@ -350,16 +350,17 @@ class UserModel implements IDBItem { ... } ``` + Добавим его в базу данных: ```php $table = 'users'; $userData = new UserModel(); -$userData->setUsername('test_user')->setEmail('test@example.com'); +$userData->Username = 'test_user'; +$userData->Email = 'test@example.com'; $result = $db->Insert($table, $userData); -if ($result !== false) { +if ($result !== false) echo "Пользователь успешно добавлен!"; -} ``` #### Пример №2: обновление данных: @@ -371,11 +372,10 @@ $newEmail = 'new_email@example.com'; // $userData - это UserModel (полученная ранее из БД) // Обновим Email -$userData->setEmail($newEmail); +$userData->Email = $newEmail; -if ($db->Update('users', $userData)) { +if ($db->Update('users', $userData)) echo "Данные пользователя успешно обновлены."; -} ``` ### Пример №3: Массовая вставка данных @@ -383,7 +383,6 @@ if ($db->Update('users', $userData)) { Допустим, вам нужно добавить несколько пользователей одним запросом: ```php -use goodboyalex\php_db_components_pack\classes\Database; use goodboyalex\php_db_components_pack\models\UserModel; // Предположим, что у вас уже инициализирован объект $db @@ -396,13 +395,11 @@ $sources[] = new UserModel(['username' => 'Bob']); // Вставляем всех пользователей разом $result = $db->InsertMany($table, ...$sources); -if ($result !== false) { - foreach ($result as $insertedId) { +if ($result !== false) + foreach ($result as $insertedId) echo "Добавлен новый пользователь с ID: $insertedId\n"; - } -} else { +else echo "Ошибка при массовом добавлении пользователей.\n"; -} ``` ### Пример №4: Проверка существования пользователя по имени @@ -413,17 +410,15 @@ if ($result !== false) { use goodboyalex\php_db_components_pack\conditions\ConditionBuilder; // Настраиваем условие -$condition = new ConditionBuilder(); -$condition->addCondition('username', '=', 'JohnDoe'); +$condition = new ConditionBuilder()->WhereEquals('username', 'JohnDoe'); // Проверяем наличие пользователя $exists = $db->IsExist('users', $condition); -if ($exists) { +if ($exists) echo "Пользователь JohnDoe уже зарегистрирован!\n"; -} else { +else echo "Пользователь JohnDoe пока не зарегистрирован.\n"; -} ``` ### Пример №5: Поиск списка пользователей старше определенного возраста @@ -434,14 +429,13 @@ if ($exists) { use goodboyalex\php_db_components_pack\conditions\ConditionBuilder; // Настройка условия -$condition = new ConditionBuilder(); -$condition->addCondition('age', '>=', 30); +$condition = new ConditionBuilder()->WhereGreaterThan('age', 30); // Загружаем всех пользователей, соответствующих условию $users = $db->GetRows('users', $condition, ['id', 'username'], '\\UserModel'); foreach ($users as $user) { - echo "Имя пользователя: {$user->getUsername()}, возраст: {$user->getAge()}\n"; + echo "Имя пользователя: {$user->Name()}, возраст: {$user->Age}\n"; } ``` @@ -456,14 +450,15 @@ use goodboyalex\php_db_components_pack\conditions\ConditionBuilder; $condition = new ConditionBuilder(); // Подсчет количества пользователей -$count = $db->Count('users', $condition); +$count = $db->Count('users'); echo "Всего зарегистрировано пользователей: $count\n"; ``` ### Пример №7: Удаление устаревших пользователей -Например, вы хотите удалить всех пользователей, чья активность была давно утрачена (предположим, пользователи с датой последнего входа больше месяца назад): +Например, вы хотите удалить всех пользователей, чья активность была давно утрачена (предположим, пользователи с датой +последнего входа больше месяца назад): ```php use goodboyalex\php_db_components_pack\conditions\ConditionBuilder; @@ -471,18 +466,17 @@ 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); +$condition = new ConditionBuilder()->WhereLessThanEqual('last_login_date', $lastMonthDate); // Удаляем старых пользователей -if ($db->Delete('users', $condition)) { +if ($db->Delete('users', $condition)) echo "Устаревшие пользователи были успешно удалены.\n"; -} else { +else echo "Ошибка при удалении устаревших пользователей.\n"; -} ``` -Эти примеры демонстрируют широкий спектр возможностей, предоставляемых классом `Database`, позволяя эффективно управлять взаимодействием с базой данных. +Эти примеры демонстрируют широкий спектр возможностей, предоставляемых классом `Database`, позволяя эффективно управлять +взаимодействием с базой данных. ## Вывод diff --git a/help/index.md b/help/index.md index d9f4c86..431bb84 100644 --- a/help/index.md +++ b/help/index.md @@ -12,6 +12,21 @@ ## Описание интерфейсов, классов и перечислений: +### Атрибуты + +- [AutoIncrement](class_desc/attributes/AutoIncrement.md) +- [Check](class_desc/attributes/Check.md) +- [Compare](class_desc/attributes/Compare.md) +- [ConvertToDB](class_desc/attributes/ConvertToDB.md) +- [DataType](class_desc/attributes/DataType.md) +- [DefaultValue](class_desc/attributes/DefaultValue.md) +- [FieldName](class_desc/attributes/FieldName.md) +- [ForeignKey](class_desc/attributes/ForeignKey.md) +- [IgnoredInDB](class_desc/attributes/IgnoredInDB.md) +- [NotNull](class_desc/attributes/NotNull.md) +- [PrimaryKey](class_desc/attributes/PrimaryKey.md) +- [Unique](class_desc/attributes/Unique.md) + ### Модели - [DataBaseColumn](class_desc/models/DataBaseColumn.md) @@ -31,6 +46,11 @@ ### Классы +- [Condition](class_desc/classes/Condition.md) +- [ConditionBuilder](class_desc/classes/ConditionBuilder.md) +- [ConditionGroup](class_desc/classes/ConditionGroup.md) +- [Database](class_desc/classes/Database.md) + #### Драйвера управления таблицами - [MySQLTableManager](class_desc/classes/tm_drivers/MySQLTableManager.md) diff --git a/sources/traits/Database/DatabaseCountExist.php b/sources/traits/Database/DatabaseCountExist.php index a994f2b..7ec057f 100644 --- a/sources/traits/Database/DatabaseCountExist.php +++ b/sources/traits/Database/DatabaseCountExist.php @@ -28,7 +28,7 @@ * * @return int Количество строк или -1, в случае ошибки. */ - public function Count (string $table, ConditionBuilder $where): int + public function Count (string $table, ConditionBuilder $where = new ConditionBuilder()): int { /** * Получаем условия. diff --git a/sources/traits/Database/DatabaseDelete.php b/sources/traits/Database/DatabaseDelete.php index 2b22ea9..a2164ad 100644 --- a/sources/traits/Database/DatabaseDelete.php +++ b/sources/traits/Database/DatabaseDelete.php @@ -27,7 +27,7 @@ * * @return bool Результат выполнения. */ - public function Delete (string $table, ConditionBuilder $where): bool + public function Delete (string $table, ConditionBuilder $where = new ConditionBuilder()): bool { /** * Получаю SQL-запрос и параметры для where. diff --git a/sources/traits/Database/DatabaseGet.php b/sources/traits/Database/DatabaseGet.php index ab6c871..09d11c8 100644 --- a/sources/traits/Database/DatabaseGet.php +++ b/sources/traits/Database/DatabaseGet.php @@ -25,13 +25,13 @@ * Извлекает одну запись из базы данных и создает соответствующий объект класса. * * @param string $table Название таблицы. - * @param ConditionBuilder $where Условия выборки. * @param array $columns Колонки, которые нужно включить в запрос. + * @param ConditionBuilder $where Условия выборки. * @param string $className Полное имя класса, реализуемого интерфейсом IDBItem. * * @return object|false Заполненный объект класса или false в случае ошибки. */ - public function GetRow (string $table, ConditionBuilder $where, array $columns = [], + public function GetRow (string $table, array $columns = [], ConditionBuilder $where = new ConditionBuilder(), string $className = "\\StdClass"): object|false { // Задаю массив параметров @@ -73,7 +73,8 @@ * * @return false|ObjectArray Массив найденных классов или false в случае ошибки. */ - public function GetRows (string $table, ConditionBuilder $where, array $columns = [], + public + function GetRows (string $table, ConditionBuilder $where, array $columns = [], string $className = "\\StdClass"): false|ObjectArray { // Задаю массив параметров @@ -122,7 +123,8 @@ * * @see Query */ - public function GetCol (string $table, string $column, ConditionBuilder $where): false|array + public + function GetCol (string $table, string $column, ConditionBuilder $where): false|array { /** * Интерпретирую условия. @@ -169,7 +171,8 @@ * * @return mixed|null Результат запроса или null в случае ошибки. */ - public function GetValue (string $table, string $column, ConditionBuilder $where): mixed + public + function GetValue (string $table, string $column, ConditionBuilder $where): mixed { // Получаю колонку по условию из таблицы $result = $this->GetCol($table, $column, $where); diff --git a/sources/traits/Database/DatabaseUpdate.php b/sources/traits/Database/DatabaseUpdate.php index 7c303ad..a216f04 100644 --- a/sources/traits/Database/DatabaseUpdate.php +++ b/sources/traits/Database/DatabaseUpdate.php @@ -57,7 +57,7 @@ $property = $primaryKeys[$i]; // - получаю ключ - $whereKey = $property->FieldName; + $whereKey = $property->Column->Name; // - получаю значение ключа, конвертируя его в БД $whereValue = call_user_func($property->ConvertToDB, $property->Value); @@ -67,7 +67,7 @@ } // Получаю запись из базы данных - $dbItem = $this->GetRow($table, $where, className: get_class($item)); + $dbItem = $this->GetRow($table, where: $where, className: get_class($item)); // Если запись не найдена if ($dbItem === false) @@ -80,7 +80,7 @@ /** * Для каждого свойства... * - * @var \goodboyalex\php_db_components_pack\models\DBItemProperty $property Свойство. + * @var DBItemProperty $property Свойство. */ foreach ($properties as $property) { // ... если это первичный ключ @@ -112,7 +112,7 @@ $value = call_user_func($property->ConvertToDB, $property->Value); // - добавляю его в массив параметров для обновления - $propertyToSet[$property->FieldName] = $value; + $propertyToSet[$property->Column->Name] = $value; } // Создаю массив set