20250810-1 v1.0

help/class_desc/attributes/Compare.md

@@ -10,25 +10,48 @@
 Например, это может понадобиться, если простое сравнение двух значений недостаточно точно отражает вашу бизнес-логику (
 например, если нужно сравнивать значения с учётом округления или игнорируя регистр букв).
 
+## Синтаксис использования
+
+Атрибут принимает один обязательный параметр типа `string|array|null`, который определяет способ сравнения. Возможны
+следующие варианты:
+
+* Строка — имя статического метода.
+* Массив — [класс, метод].
+* null — сравнение по умолчанию.
+
 ## Пример использования атрибута
 
-Допустим, у вас есть модель данных, включающая поле, содержащее имя пользователя, и вы хотите сравнить имена независимо
-от регистра:
+### Пример 1: Использование статического метода
 
 ```php
 use goodboyalex\php_db_components_pack\attributes\Compare;
 
 final class User
 {
-    #[Compare(fn($left, $right) => strcasecmp($left, $right))]
-    private string $Name;
-
-    // Остальные поля и геттеры/сеттеры...
+    #[Compare('App\Comparators\StringComparator::caseInsensitiveCompare')]
+    public string $Name;
 }
 ```
 
-В данном примере атрибут `#[Compare]` применяется к полю `$Name`, и указанное замыкание (closure) реализует
-сравнение строк без учёта регистра.
+#### Пример 2: Использование массива для вызова метода
+
+```php
+final class Measurement
+{
+    #[Compare('App\Comparators\NumberComparator', 'compareWithTolerance')]
+    public float $Value;
+}
+```
+
+#### Пример 3: Сравнение по умолчанию
+
+```php
+final class Event
+{
+    #[Compare(null)]
+    public string $Date;
+}
+```
 
 ## Пространство имён
 
@@ -49,6 +72,13 @@ namespace goodboyalex\php_db_components_pack\attributes;
 - **Применяется только к полям (properties)**  
   Атрибут используется исключительно для аннотирования полей классов, которые соответствуют столбцам базы данных.
 
+## Важные замечания
+
+* Все указанные методы должны быть статическими.
+* При некорректном определении компаратора будет выброшено исключение.
+* Рекомендуется создавать отдельные классы компараторов для лучшей поддерживаемости кода.
+* Методы сравнения должны корректно обрабатывать все возможные значения поля.
+
 ## Когда использовать атрибут?
 
 Атрибут `Compare` идеально подойдёт, когда вам необходимо установить особое правило сравнения значений. Например, если

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)**  
-  Атрибут используется исключительно для аннотирования полей классов, которые соответствуют столбцам базы данных.
+* Атрибут применяется только к свойствам класса
+* Поддерживает два формата определения конвертаций
+* Автоматически создаёт замыкания на основе переданных данных
+* Позволяет использовать любые статические методы для конвертации
 
 ## Когда использовать атрибут?