20250807

2025-08-07 18:06:55 +03:00
parent eeea57209e
commit d132832d28
34 changed files with 1231 additions and 286 deletions
--- a/help/class_desc/models/DBItemProperty.md
+++ b/help/class_desc/models/DBItemProperty.md
@@ -0,0 +1,97 @@
+# Класс `DBItemProperty`
+
+Класс `DBItemProperty` предназначен для описания отдельного свойства объекта, реализующего интерфейс `IDBItem`. Он
+предоставляет полную информацию о свойствах объекта, предназначенных для хранения в базе данных, включая имя, значение,
+тип данных, правила преобразования и сравнение.
+
+## Пространство имён
+
+```php
+namespace goodboyalex\php_db_components_pack\models;
+```
+
+## Автор и версия
+
+- **Автор**: Александр Бабаев
+- **Версия**: 1.0
+- **Дата начала поддержки**: с версии 1.0
+
+## Назначение
+
+Класс `DBItemProperty` описывает отдельную сущность — объект и его свойства, предназначенного для хранения в базе
+данных. Помимо основного значения, он также хранит информацию о том, как это свойство будет отражаться в базе данных
+(например, имя колонки, тип данных, преобразователи и правила игнорирования).
+
+## Основные элементы класса
+
+### Поля
+
+## Поля класса `DBItemProperty`
+
+| Имя поля      | Тип поля       | Описание                                                                                                     |
+|---------------|----------------|--------------------------------------------------------------------------------------------------------------|
+| Name          | string         | Имя свойства в объекте.                                                                                      |
+| Value         | mixed          | Текущее значение свойства (до преобразования).                                                               |
+| Column        | DataBaseColumn | Объект, описывающий характеристики колонки в базе данных (тип данных, ограничения и т.д.).                   |
+| IsIgnored     | bool           | Признак, указывающий, что данное свойство игнорируется при сохранении в базу данных или загрузке из неё.     |                                                                                                     |
+| ConvertToDB   | Closure        | Замыкание, осуществляющее преобразование значения свойства в формат, подходящий для записи в базу данных.    |
+| ConvertFromDB | Closure        | Замыкание, осуществляющее обратное преобразование из формата базы данных в формат внутреннего представления. |
+| Compare       | Closure        | Замыкание, позволяющее сравнивать значения свойства.                                                         |
+
+### Конструктор
+
+Позволяет сконструировать объект с полной информацией о свойстве, включая имя, значение, связь с колонкой базы данных и
+средства преобразования и сравнения.
+
+## Пример использования
+
+Допустим, у вас есть объект пользователя, и вы хотите описать свойство `username` следующим образом:
+
+```php
+use goodboyalex\php_db_components_pack\models\DBItemProperty;
+use goodboyalex\php_db_components_pack\models\DataBaseColumn;
+use goodboyalex\php_db_components_pack\enums\DBType;
+
+// Создаём объект свойства username
+$property = new DBItemProperty(
+    // Имя свойства
+    'username',
+    // Текущее значение
+    'john_doe',
+    // Характеристики колонки
+    new DataBaseColumn(
+        // - имя колонки в базе данных
+        'user_name',
+        // - тип данных (строка, макс. 255 символов)
+        new Tuple(DBType::STRING, 255),
+        // - NOT NULL
+        true,
+        // - UNIQUE
+        true,
+        // - не первичный ключ
+        false,
+        // - без внешнего ключа
+        new Tuple(null, null),
+        // - без проверок
+        new ConditionBuilder(),
+        // - значение по умолчанию
+        ''
+    ),
+    // Не игнорируется
+    false,
+    // Преобразование в нижний регистр перед сохранением
+    function ($value) { return strtolower($value); },
+    // Преобразование в Title Case при получении
+    function ($value) { return ucfirst($value); },
+    // Функция сравнения
+    function ($left, $right) { return strcmp($left, $right); }
+);
+```
+
+## Дополнительная информация
+
+Класс `DBItemProperty` является важной составляющей инфраструктуры для работы с объектами, предназначенными для хранения
+в базе данных. Он позволяет детально описывать свойства объектов, включая преобразования и правила загрузки/записи, что
+существенно упрощает интеграцию с базой данных и повышает гибкость работы с данными.
+
+[На главную](../../index.md)