20250806

help/class_desc/attributes/Compare.md

@@ -0,0 +1,58 @@
+# Атрибут `Compare`
+
+Атрибут `Compare` предназначен для задания специальных процедур сравнения значений поля при работе с базой данных. Он
+позволяет реализовать кастомные механизмы сравнения, отличающиеся от стандартного равенства, что бывает крайне полезно
+при сложной логике работы с данными.
+
+## Основное назначение
+
+Атрибут позволяет указать собственный метод сравнения значений, применяемый к определенному полю в базе данных.
+Например, это может понадобиться, если простое сравнение двух значений недостаточно точно отражает вашу бизнес-логику (
+например, если нужно сравнивать значения с учётом округления или игнорируя регистр букв).
+
+## Пример использования атрибута
+
+Допустим, у вас есть модель данных, включающая поле, содержащее имя пользователя, и вы хотите сравнить имена независимо
+от регистра:
+
+```php
+use goodboyalex\php_db_components_pack\attributes\Compare;
+
+final class User
+{
+    #[Compare(fn($left, $right) => strcasecmp($left, $right))]
+    private string $Name;
+
+    // Остальные поля и геттеры/сеттеры...
+}
+```
+
+В данном примере атрибут `#[Compare]` применяется к полю `$Name`, и указанное замыкание (closure) реализует
+сравнение строк без учёта регистра.
+
+## Пространство имён
+
+Атрибут объявлен в пространстве имён:
+
+```php
+namespace goodboyalex\php_db_components_pack\attributes;
+```
+
+### Версии и автор
+
+- **Автор**: Александр Бабаев
+- **Версия**: 1.0
+- **Дата выпуска**: с версии 1.0
+
+## Особенности
+
+- **Применяется только к полям (properties)**  
+  Атрибут используется исключительно для аннотирования полей классов, которые соответствуют столбцам базы данных.
+
+## Когда использовать атрибут?
+
+Атрибут `Compare` идеально подойдёт, когда вам необходимо установить особое правило сравнения значений. Например, если
+требуется учесть особенности сортировки, учета регистров или даже допустимые погрешности при сравнении числовых
+значений.
+
+[На главную](../../index.md)