20250805-1

help/basic_usage/usage_preparation.md

@@ -2,7 +2,7 @@
 
 Чтобы начать пользоваться классом, необходимо для начала прописать настройки соединения с базой данных.
 
-Для этого создадим класс [DBConfig](../class_desc/DBConfig.md) с конфигурацией подключения к базе данных:
+Для этого создадим класс [DBConfig](../class_desc/models/DBConfig.md) с конфигурацией подключения к базе данных:
 
 ```php
 $db_config = new DBConfig(
@@ -16,9 +16,9 @@ $db_config = new DBConfig(
 );
 ```
 
-Первым параметром идёт драйвер СУБД, представленный перечислением [DBDriver](../class_desc/DBDriver.md), затем сервер БД, порт, её имя, пользователь, пароль и ключ для шифрования (_если используете действия интерфейса ISerializable_).
+Первым параметром идёт драйвер СУБД, представленный перечислением [DBDriver](../class_desc/enums/DBDriver.md), затем сервер БД, порт, её имя, пользователь, пароль и ключ для шифрования (_если используете действия интерфейса ISerializable_).
 
-Итак, настройки созданы, время создать сам класс [Database](../class_desc/Database.md)
+Итак, настройки созданы, время создать сам класс [Database](../class_desc/classes/Database.md)
 
 
 [На главную](../index.md) | [Следующий пункт](../index.md)

help/class_desc/classes/Database.md

@@ -489,4 +489,4 @@ if ($db->Delete('users', $condition)) {
 Таким образом, этот класс предоставляет удобные инструменты для реализации большинства стандартных операций с базой
 данных на уровне ORM-подхода.
 
-[На главную](../index.md)
+[На главную](../../index.md)

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)

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)

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)

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)

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)

help/class_desc/enums/DBDriver.md

@@ -1,10 +1,14 @@
 # Перечисление `DBDriver`
 
-## Описание
-
 Перечисление представляет собой набор констант, определяющих типы драйверов баз данных, поддерживаемых системой.
 Используется совместно с библиотекой PHP PDO для идентификации различных типов СУБД.
 
+## Основная информация
+
+- **Автор**: Александр Бабаев
+- **Версия**: 1.0
+- **Дата начала поддержки**: с версии 1.0
+
 ## Пространство имен и зависимости
 
 ```php
@@ -13,7 +17,7 @@ namespace goodboyalex\php_db_components_pack\enums;
 use goodboyalex\php_components_pack\traits\EnumExtensionsTrait;
 ```
 
-## Константы
+## Возможные значения перечисления
 
 |  Константа   | Значение | Описание              |
 |:------------:|:--------:|-----------------------|
@@ -49,7 +53,9 @@ if ($dbType === DBDriver::MySQL)
 `enum`). Если используется более ранняя версия PHP, возможно потребуется альтернативная реализация на основе классов или
 сторонних пакетов.
 
----
+## Вывод
 
 Этот класс является частью библиотеки `goodboyalex/php_db_components_pack` и предназначен для унификации работы с
-различными системами управления базами данных посредством стандартного интерфейса PDO.
+различными системами управления базами данных посредством стандартного интерфейса PDO.
+
+[На гравную](../../index.md)

help/class_desc/enums/DBOperation.md

@@ -0,0 +1,82 @@
+# Перечисление `DBOperation`
+
+Перечисление `DBOperation` представляет собой перечень возможных операций, выполняемых над базой данных. Эти операции
+используются для обозначения действий, связанных с управлением данными и таблицами, такими как вставка, получение,
+обновление, удаление и подсчет элементов, а также создание и удаление таблиц.
+
+## Основная информация
+
+- **Автор**: Александр Бабаев
+- **Версия**: 1.0
+- **Дата начала поддержки**: с версии 1.0
+
+## Пространство имен и зависимости
+
+```php
+namespace goodboyalex\php_db_components_pack\enums;
+
+use goodboyalex\php_components_pack\traits\EnumExtensionsTrait;
+```
+
+## Возможные значения перечисления
+
+1. **Insert** (`case Insert = 0`)  
+   Операция вставки данных в базу данных.
+
+2. **Get** (`case Get = 1`)  
+   Операция получения данных из базы данных.
+
+3. **Update** (`case Update = 2`)  
+   Операция обновления существующего элемента в базе данных.
+
+4. **Delete** (`case Delete = 3`)  
+   Операция удаления элемента из базы данных.
+
+5. **Count** (`case Count = 4`)  
+   Операция подсчёта количества элементов в базе данных.
+
+6. **CreateTable** (`case CreateTable = 5`)  
+   Операция создания новой таблицы в базе данных.
+
+7. **DropTable** (`case DropTable = 6`)  
+   Операция удаления существующей таблицы из базы данных.
+
+## Особенности
+
+- **Наследует трейт `EnumExtensionsTrait`**: Предоставляет дополнительный функционал для расширения возможностей работы
+  с перечислениями, включая вспомогательные методы для удобного обращения к элементам перечисления.
+
+## Использование перечисления
+
+Пример использования перечисления в вашем приложении:
+
+```php
+use goodboyalex\php_db_components_pack\enums\DBOperation;
+
+// Определили операцию вставки
+$operation = DBOperation::Insert;
+
+switch ($operation) {
+    case DBOperation::Insert:
+        echo "Операция вставки данных.";
+        break;
+    case DBOperation::Get:
+        echo "Операция получения данных.";
+        break;
+    default:
+        echo "Другая операция.";
+}
+```
+
+## Совместимость
+
+Перечисление совместимо с современными версиями PHP, начиная с версии 8.1, поддерживающей нативные перечисления (
+`enum`). Если используется более ранняя версия PHP, возможно потребуется альтернативная реализация на основе классов или
+сторонних пакетов.
+
+## Вывод
+
+Этот класс является частью библиотеки `goodboyalex/php_db_components_pack` и предназначен для унификации работы с
+различными системами управления базами данных посредством стандартного интерфейса PDO.
+
+[На гравную](../../index.md)

help/class_desc/enums/DBType.md

@@ -0,0 +1,77 @@
+# Перечисление `DBType`
+
+Перечисление `DBType` описывает возможные типы данных, используемые в системах управления базами данных (СУБД). Оно
+позволяет удобно сопоставлять стандартные типы данных PHP с типом данных, соответствующим выбранной СУБД.
+
+## Основная информация
+
+- **Автор**: Александр Бабаев
+- **Версия**: 1.0
+- **Дата начала поддержки**: с версии 1.0
+
+## Пространство имен и зависимости
+
+```php
+namespace goodboyalex\php_db_components_pack\enums;
+
+use goodboyalex\php_components_pack\traits\EnumExtensionsTrait;
+```
+
+## Элементы перечисления
+
+1. **INT** (`case INT = 0`)  
+   Целочисленный тип данных.
+
+2. **FLOAT** (`case FLOAT = 1`)  
+   Тип данных с плавающей точкой.
+
+3. **STRING** (`case STRING = 2`)  
+   Строковый тип данных.
+
+4. **BOOL** (`case BOOL = 3`)  
+   Булевый тип данных.
+
+5. **DATE** (`case DATE = 4`)  
+   Дата-время.
+
+6. **ARRAY** (`case ARRAY = 5`)  
+   Массивы или коллекции данных.
+
+## Особенности
+
+- **Наследует трейт `EnumExtensionsTrait`**: Трейт расширяет функциональные возможности перечислений, предоставляя
+  удобные методы для манипуляции значениями перечисления.
+
+- **Статический метод `ToSQLType`**: Позволяет перевести тип данных из PHP в эквивалентный тип данных соответствующей
+  СУБД. Например, если указана СУБД MySQL, метод вернёт правильный SQL-тип, исходя из указанного типа данных.
+
+## Использование перечисления
+
+Пример использования перечисления для перевода типа данных:
+
+```php
+use goodboyalex\php_db_components_pack\enums\DBType;
+use goodboyalex\php_db_components_pack\enums\DBDriver;
+
+// Определение типа данных и драйвера
+$dataType = DBType::STRING;
+$driver = DBDriver::MySQL;
+
+// Преобразование типа данных в SQL-эквивалент
+$sqlType = DBType::ToSQLType($driver, $dataType);
+
+echo "Эквивалентный SQL-тип: $sqlType"; // Output: VARCHAR
+```
+
+## Совместимость
+
+Перечисление совместимо с современными версиями PHP, начиная с версии 8.1, поддерживающей нативные перечисления (
+`enum`). Если используется более ранняя версия PHP, возможно потребуется альтернативная реализация на основе классов или
+сторонних пакетов.
+
+## Вывод
+
+Этот класс является частью библиотеки `goodboyalex/php_db_components_pack` и предназначен для унификации работы с
+различными системами управления базами данных посредством стандартного интерфейса PDO.
+
+[На гравную](../../index.md)

help/class_desc/interfaces/IDBItem.md

@@ -0,0 +1,93 @@
+# Интерфейс `IDBItem`
+
+## Пространство имен
+
+```php
+goodboyalex\php_db_components_pack\interfaces
+```
+
+## Назначение
+
+Данный интерфейс определяет контракт для классов и моделей, используемых в качестве сущностей базы данных. Реализуя этот
+интерфейс, разработчик обеспечивает совместимость своих моделей с функциями CRUD (создание, чтение, обновление,
+удаление), предоставляемыми классом `Database`.
+
+## Версия и автор
+
+- **Автор**: Александр Бабаев
+- **Версия**: 1.0
+- **Дата начала поддержки**: с версии 1.0
+
+## Возможности интерфейса
+
+Несмотря на то, что сам интерфейс не включает никаких обязательных методов, он сигнализирует о принадлежности
+конкретного класса к категории объектов, поддерживающих хранение и обработку в базе данных. Это позволяет другим
+компонентам системы (таким как класс `Database`) легко распознавать и правильно обрабатывать такие сущности.
+
+## Использование интерфейса
+
+Реализация интерфейса `IDBItem` подразумевает стандартизацию способов хранения и обработки свойств класса в базе данных.
+Рассмотрим простой пример модели, реализующей интерфейс `IDBItem`:
+
+```php
+<?php
+
+namespace App\Models;
+
+use goodboyalex\php_db_components_pack\attributes\AutoIncrement;
+use goodboyalex\php_db_components_pack\attributes\FieldName;
+use goodboyalex\php_db_components_pack\attributes\NotNull;
+use goodboyalex\php_db_components_pack\attributes\PrimaryKey;
+use goodboyalex\php_db_components_pack\attributes\Unique;
+use goodboyalex\php_db_components_pack\interfaces\IDBItem;
+
+class User implements IDBItem
+{
+    /**
+    * @var int $Id Идентификатор пользователя.
+    */
+    #[PrimaryKey, NotNull, AutoIncrement, FieldName('id'), Unique]
+    public int $Id = 0;
+    
+    /**
+    * @var string $Name Имя пользователя.
+    */
+    #[NotNull, FieldName('user_name')]
+    public string $Name = '';
+    
+    /**
+    * @var string $Email Почта пользователя. 
+    */
+    #[NotNull, FieldName('user_mail')]
+    public string $Email = '';
+}
+```
+
+## Применение в классе `Database`
+
+При работе с экземплярами класса `Database`, реализация интерфейса `IDBItem` необходима для корректного взаимодействия
+моделей с методами CRUD. Например, метод `Insert()` ожидает аргумент, реализующий интерфейс `IDBItem`, для вставки
+данных в базу.
+
+Примеры методов, использующих интерфейс `IDBItem`:
+
+- `Insert($table, IDBItem $row)`
+- `InsertMany($table, IDBItem ...$sources)`
+- `Update($table, IDBItem $item)`
+- `UpdateMany($table, IDBItem ...$items)`
+
+## Преимущества использования интерфейса
+
+1. **Типизация**: Четкое определение требований к классу делает код проще для понимания и поддержания.
+
+2. **Совместимость**: Любая модель, реализующая интерфейс `IDBItem`, становится доступной для стандартных функций базы
+   данных, обеспечиваемых пакетом.
+
+3. **Безопасность**: Позволяет избежать случайных ошибок путем ограничения типов аргументов метода.
+
+## Вывод
+
+Использование интерфейса `IDBItem` значительно упрощает интеграцию ваших собственных моделей с функциональностью пакета,
+обеспечивая удобный и структурированный способ работы с базой данных.
+
+[На главную](../../index.md)

help/class_desc/interfaces/ITableManager.md

@@ -0,0 +1,79 @@
+# Интерфейс `ITableManager`
+
+Интерфейс `ITableManager` предназначен для унификации работы с различными системами управления базами данных (СУБД) и
+представляет собой общий API для управления таблицами в базе данных. Интерфейс помогает абстрагироваться от конкретных
+особенностей разных драйверов баз данных и облегчает поддержку различных СУБД внутри приложения.
+
+## Информация
+
+- **Название пространства имён**: `goodboyalex\php_db_components_pack\interfaces`
+- **Автор**: Александр Бабаев
+- **Версия**: 1.0
+- **Начало поддержки**: с версии 1.0
+
+## Свойства
+
+### `public array $TypeConversation`
+
+Это свойство предназначено для хранения соответствия типов данных PHP и определённых СУБД. Оно используется для
+правильного преобразования типов данных при создании и изменении таблиц.
+
+Пример использования:
+
+```php
+use goodboyalex\php_db_components_pack\enums\DBType;
+
+$this->TypeConversation[DBType::INT] = 'INT'; // Для MySQL
+$this->TypeConversation[DBType::STRING] = 'VARCHAR'; // Для MySQL
+```
+
+## Методы
+
+### `IsTableExist(PDO $handle, string $tableName): bool`
+
+Метод проверяет, существует ли таблица с данным именем в базе данных.
+
+**Параметры**:
+
+- `$handle`: объект PDO, представляющий соединение с базой данных.
+- `$tableName`: название таблицы, которую нужно проверить.
+
+**Возвращаемый результат**:
+
+- `true`, если таблица существует.
+- `false`, если таблица не найдена.
+
+### `CreateTable(PDO $handle, string $tableName, ObjectArray $columns): bool`
+
+Метод создаёт новую таблицу в базе данных.
+
+**Параметры**:
+
+- `$handle`: объект PDO, представляющий соединение с базой данных.
+- `$tableName`: название новой таблицы.
+- `$columns`: массив объектов `DataBaseColumn`, описывающих структуру таблицы.
+
+**Возвращаемый результат**:
+
+- `true`, если таблица успешно создана.
+- `false`, если возникла ошибка при создании таблицы.
+
+### `ParseColumn(DataBaseColumn $column): string`
+
+Этот метод генерирует правильное представление столбца таблицы в виде SQL-кода, основываясь на переданных параметрах.
+
+**Параметры**:
+
+- `$column`: объект `DataBaseColumn`, описывающий столбец таблицы.
+
+**Возвращаемый результат**:
+
+- SQL-код, представляющий указанный столбец таблицы.
+
+## Типичные сценарии использования
+
+Это внутренний интерфейс, его реализуют драйвера управления
+таблицами: [MySQLTableManager](../classes/tm_drivers/MySQLTableManager.md), [MSSQLTableManager](../classes/tm_drivers/MSSQLTableManager.md), [PostgreSQLTableManager](../classes/tm_drivers/PostgreSQLTableManager.md), [OracleDBTableManager](../classes/tm_drivers/OracleDBTableManager.md)
+и [SQLiteTableManager](../classes/tm_drivers/SQLiteTableManager.md)
+
+[На главную](../../index.md)

help/class_desc/models/DBConfig.md

@@ -105,4 +105,4 @@ echo $config->Host; // Выведет: localhost
 Данный класс является частью пакета `goodboyalex/php_db_components_pack`. Для полноценной работы рекомендуется
 ознакомиться с документацией по пакету и зависимым компонентам.
 
-[На главную](../index.md)
+[На главную](../../index.md)

help/index.md

@@ -1,16 +1,38 @@
 # Добро пожаловать в справочное руководство по компонентам PHP DB COMPONENTS PACK!
 
-## Руководство актуально для версии v1.0
+**Руководство актуально для версии v1.0**
 
-## Автор: Александр Бабаев
+**Автор: Александр Бабаев**
 
-### Выберете интересующий Вас раздел:
+## Выберете интересующий Вас раздел:
 
-### Базовое использование:
+## Базовое использование:
 
 - [Подготовка к использованию](basic_usage/usage_preparation.md)
 
-##### Описание интерфейсов, классов и перечислений:
+## Описание интерфейсов, классов и перечислений:
 
-- [DBConfig](class_desc/DBConfig.md)
+### Модели
-- [DBDriver](class_desc/DBDriver.md)
+
+- [DBConfig](class_desc/models/DBConfig.md)
+
+### Перечисления
+
+- [DBDriver](class_desc/enums/DBDriver.md)
+- [DBOperation](class_desc/enums/DBOperation.md)
+- [DBType](class_desc/enums/DBType.md)
+
+### Интерфейсы
+
+- [IDBItem](class_desc/interfaces/IDBItem.md)
+- [ITableManager](class_desc/interfaces/ITableManager.md)
+
+### Классы
+
+#### Драйвера управления таблицами
+
+- [MySQLTableManager](class_desc/classes/tm_drivers/MySQLTableManager.md)
+- [MSSQLTableManager](class_desc/classes/tm_drivers/MSSQLTableManager.md)
+- [PostgreSQLTableManager](class_desc/classes/tm_drivers/PostgreSQLTableManager.md)
+- [OracleDBTableManager](class_desc/classes/tm_drivers/OracleDBTableManager.md)
+- [SQLiteTableManager](class_desc/classes/tm_drivers/SQLiteTableManager.md)