babaev-an / ANB PHP COMPONENTS PACK

interfaces/IValidator.md

Интерфейс IValidator

Пространство имён: goodboyalex\php_components_pack\interfaces

Версия: 1.0

Доступно с: 1.5.9

Описание

Интерфейс определяет контракт для классов-валидаторов, предназначенных для проверки данных на соответствие определенным правилам и преобразования их в целевой тип. Является фундаментальной частью системы обеспечения целостности данных (Data Integrity) во всем компоненте.

Методы интерфейса

Метод validate

public function validate(mixed $value, bool $nullable = true): ActionState

Описание

Проверяет элемент на выполнение условия валидности. Метод выполняет двойную функцию: верификацию входных данных и их безопасное приведение к целевому типу (sanitization).

Параметры

  • $value (mixed) — проверяемый элемент произвольного типа.
  • $nullable (bool, необязательный) — флаг, разрешающий значение null. По умолчанию true.

Возвращаемое значение

ActionState — объект состояния операции. В случае успеха не будет ошибок и метод isSuccess вернёт true, а в свойстве value вернется сконвертированный (очищенный) элемент. При неудаче лобавляются ошибки с описанием причины сбоя.

Пример использования

class EmailValidator implements IValidator {
    public function validate(mixed $value, bool $nullable = true): ActionState {
        $stringClass = $nullable ? '?string' : 'string';
        
        $result = new ActionState('', $stringClass);
        
        if ($value === null && $nullable){
            $result->value = null;
            return $result; 
        }

        if (!is_string($value)) {
            $result->addError('Значение должно быть строкой');
            return $result;
        }

        if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {
            $result->addError('Некорректный формат email-адреса.');
            return $result;
        }
        
        // Нормализуем значение
        $result->value = mb_strtolower(trim($value));
        
        // Возвращаем его
        return new ActionState(true, );
    }

}

// Применение
$validator = new EmailValidator();
$result = $validator->validate(' EXAMPLE@Domain.com ');

if ($result->isSuccess())
    echo "Валидный email: " . $result->value; // example@domain.com
else
    echo "Ошибка: " . $result->getStringMessages(ActionState::GET_STRING_ERROR_ONLY);

Рекомендации по использованию

При реализации интерфейса:

  • всегда возвращайте результат строго через объект ActionState;
  • не используйте исключения (throw) для управления потоком бизнес-логики при штатной валидации;
  • обеспечивайте идемпотентность: повторная передача уже валидированного значения не должна менять состояние объекта или вызывать ошибку;
  • выполняйте нормализацию данных перед возвратом успешного результата (например, обрезку пробелов, приведение регистра);
  • если параметр $nullable установлен в false, а передано значение null, метод должен вернуть ActionState со статусом ошибки.

При работе с данными:

  • используйте цепочки валидаторов (Pipeline), где выход одного валидатора подается на вход следующего;
  • группируйте логические наборы правил в составные валидаторы (Composite Validator) для сложных DTO;
  • для пользовательского ввода всегда применяйте строгую проверку типов до начала бизнес-валидации;
  • журналируйте содержимое ошибок только на уровне контроллеров/приложения, сами валидаторы должны оставаться чистыми от побочных эффектов.

На главную | Содержание

Назад