# Атрибут `Compare`

Атрибут `Compare` предназначен для задания специальных процедур сравнения значений поля при работе с базой данных. Он
позволяет реализовать кастомные механизмы сравнения, отличающиеся от стандартного равенства, что бывает крайне полезно
при сложной логике работы с данными.

## Основное назначение

Атрибут позволяет указать собственный метод сравнения значений, применяемый к определенному полю в базе данных.
Например, это может понадобиться, если простое сравнение двух значений недостаточно точно отражает вашу бизнес-логику (
например, если нужно сравнивать значения с учётом округления или игнорируя регистр букв).

## Синтаксис использования

Атрибут принимает один обязательный параметр типа `string|array|null`, который определяет способ сравнения. Возможны
следующие варианты:

* Строка — имя статического метода.
* Массив — [класс, метод].
* null — сравнение по умолчанию.

## Пример использования атрибута

### Пример 1: Использование статического метода

```php
use goodboyalex\php_db_components_pack\attributes\Compare;

final class User
{
    #[Compare('App\Comparators\StringComparator::caseInsensitiveCompare')]
    public string $Name;
}
```

#### Пример 2: Использование массива для вызова метода

```php
final class Measurement
{
    #[Compare('App\Comparators\NumberComparator', 'compareWithTolerance')]
    public float $Value;
}
```

#### Пример 3: Сравнение по умолчанию

```php
final class Event
{
    #[Compare(null)]
    public string $Date;
}
```

## Пространство имён

Атрибут объявлен в пространстве имён:

```php
namespace goodboyalex\php_db_components_pack\attributes;
```

### Версии и автор

- **Автор**: Александр Бабаев
- **Версия**: 1.0
- **Дата выпуска**: с версии 1.0

## Особенности

- **Применяется только к полям (properties)**  
  Атрибут используется исключительно для аннотирования полей классов, которые соответствуют столбцам базы данных.

## Важные замечания

* Все указанные методы должны быть статическими.
* При некорректном определении компаратора будет выброшено исключение.
* Рекомендуется создавать отдельные классы компараторов для лучшей поддерживаемости кода.
* Методы сравнения должны корректно обрабатывать все возможные значения поля.

## Когда использовать атрибут?

Атрибут `Compare` идеально подойдёт, когда вам необходимо установить особое правило сравнения значений. Например, если
требуется учесть особенности сортировки, учета регистров или даже допустимые погрешности при сравнении числовых
значений.

[На главную](../../index.md)