20250806

help/class_desc/attributes/ConvertToDB.md

@@ -0,0 +1,63 @@
+# Атрибут `ConvertToDB`
+
+Атрибут `ConvertToDB` предназначен для настройки процесса преобразования значений при взаимодействии с базой данных. Он
+позволяет задать специальные методы для преобразования данных между внутренним представлением и формой, подходящей для
+сохранения в базе данных.
+
+## Основное назначение
+
+Атрибут позволяет настроить индивидуальные процедуры для преобразования данных, поступающих из базы данных и обратно.
+Часто бывает необходимо изменять формат данных при передаче их между слоями приложения и хранилищем, например,
+преобразовать JSON в объект или нормализовать строку для хранения в определенном формате.
+
+## Пример использования атрибута
+
+Допустим, у вас есть модель данных, содержащая поле, которое хранит метаданные в формате JSON, и вы хотите, чтобы это
+поле было сериализовано в JSON при сохранении в базу данных и десериализовано обратно при извлечении:
+
+```php
+use goodboyalex\php_db_components_pack\attributes\ConvertToDB;
+use goodboyalex\php_db_components_pack\attributes\DataType;
+use goodboyalex\php_db_components_pack\enums\DBType;
+
+final class Product
+{
+    #[ConvertToDB(
+        fromType: fn($val) => json_decode($val, true),
+        toType: fn($val) => json_encode($val)
+    ), DataType(DBType::STRING)]
+    public array $MetaData;
+
+    // Другие поля и геттеры/сеттеры...
+}
+```
+
+В данном примере атрибут `#[ConvertToDB]` применяется к полю `$MetaData`, и два заданных замыкания определяют порядок
+преобразования данных при чтении и записи.
+
+## Пространство имён
+
+Атрибут объявлен в пространстве имён:
+
+```php
+namespace goodboyalex\php_db_components_pack\attributes;
+```
+
+## Версии и автор
+
+- **Автор**: Александр Бабаев
+- **Версия**: 1.0
+- **Дата выпуска**: с версии 1.0
+
+## Особенности
+
+- **Применяется только к полям (properties)**  
+  Атрибут используется исключительно для аннотирования полей классов, которые соответствуют столбцам базы данных.
+
+## Когда использовать атрибут?
+
+Атрибут `ConvertToDB` пригодится, когда возникает необходимость нестандартного преобразования данных. Например, если вы
+работаете с JSON-данными, XML-документами или бинарными изображениями, и нужно аккуратно сохранять и извлекать эти
+данные из базы данных.
+
+[На главную](../../index.md)