20250805-1

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)