20250810-1 v1.0

help/class_desc/attributes/ConvertToDB.md

@@ -10,10 +10,16 @@
 Часто бывает необходимо изменять формат данных при передаче их между слоями приложения и хранилищем, например,
 преобразовать JSON в объект или нормализовать строку для хранения в определенном формате.
 
-## Пример использования атрибута
+## Синтаксис использования
 
-Допустим, у вас есть модель данных, содержащая поле, которое хранит метаданные в формате JSON, и вы хотите, чтобы это
-поле было сериализовано в JSON при сохранении в базу данных и десериализовано обратно при извлечении:
+Атрибут принимает два параметра:
+
+* **fromType** - определение конвертации из БД (может быть строкой, массивом или `null`). По умолчанию, `null`.
+* **toType** - определение конвертации в БД (может быть строкой, массивом или `null`). По умолчанию, `null`.
+
+### Примеры использования
+
+#### Пример 1: Использование строковых вызовов
 
 ```php
 use goodboyalex\php_db_components_pack\attributes\ConvertToDB;
@@ -23,17 +29,34 @@ 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)]
+        'App\Converters\JsonConverter::decode',
+        'App\Converters\JsonConverter::encode'
+    )]
     public array $MetaData;
-
-    // Другие поля и геттеры/сеттеры...
 }
 ```
 
-В данном примере атрибут `#[ConvertToDB]` применяется к полю `$MetaData`, и два заданных замыкания определяют порядок
-преобразования данных при чтении и записи.
+#### Пример 2: Использование массивов для вызова методов
+
+```php
+final class Product
+{
+    #[ConvertToDB(
+        ['App\Converters\DateConverter', 'convertToInternal'],
+        ['App\Converters\DateConverter', 'convertToDB']
+    )]
+    public string $created_at;
+}
+```
+
+## Параметры атрибута
+
+* **fromType** (string|array|null) - определение конвертации из БД
+    * Строка: имя статического метода
+    * Массив: [класс, метод]
+* **toType** (string|array|null) - определение конвертации в БД
+    * Строка: имя статического метода
+    * Массив: [класс, метод]
 
 ## Пространство имён
 
@@ -51,8 +74,10 @@ namespace goodboyalex\php_db_components_pack\attributes;
 
 ## Особенности
 
-- **Применяется только к полям (properties)**  
-  Атрибут используется исключительно для аннотирования полей классов, которые соответствуют столбцам базы данных.
+* Атрибут применяется только к свойствам класса
+* Поддерживает два формата определения конвертаций
+* Автоматически создаёт замыкания на основе переданных данных
+* Позволяет использовать любые статические методы для конвертации
 
 ## Когда использовать атрибут?