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)