<?php

/**
 * JCOGS Image Pro - Validator Interface
 * ======================================
 * Contract for all parameter validators
 * 
 * @category   ExpressionEngine Add-on
 * @package    JCOGS Image Pro
 * @author     JCOGS Design <contact@jcogs.net>
 * @copyright  Copyright (c) 2021 - 2025 JCOGS Design
 * @license    https://jcogs.net/add-ons/license/jcogs_img_pro
 * @version    2.0.6
 * @link       https://JCOGS.net/
 * @since      2.0.0
 */

namespace JCOGSDesign\JCOGSImagePro\Service\Validation;

/**
 * Validator Interface
 * 
 * Contract for all parameter validators in JCOGS Image Pro.
 * 
 * Validators are primitive building blocks that validate single values against
 * specific rules. They can be used by:
 * 
 * 1. ParameterRegistry - Validates simple parameters (width, height, quality)
 * 2. Custom ParameterPackages - Use validators via validateValue() for sub-components
 * 3. Pipeline/Filters - Replace scattered validation with centralized calls
 * 
 * Example Usage:
 * 
 * ```php
 * // Simple numeric validation
 * $validator = new NumericValidator(['min' => 1, 'max' => 100]);
 * $result = $validator->validate(50);
 * if ($result->success) {
 *     echo "Valid: " . $result->sanitizedValue;
 * }
 * 
 * // Enum validation with case-insensitive matching
 * $validator = new EnumValidator([
 *     'allowed_values' => ['contain', 'cover', 'fill'],
 *     'case_sensitive' => false
 * ]);
 * $result = $validator->validate('CONTAIN');
 * // Returns success with sanitizedValue = 'contain'
 * ```
 * 
 * Config Parameter:
 * 
 * The optional $config parameter allows runtime configuration without creating
 * specialized validator classes. For example, the same EnumValidator can validate
 * different sets of allowed values by passing different configs.
 * 
 * @package JCOGSDesign\JCOGSImagePro\Service\Validation
 * @since 2.0.0
 */
interface ValidatorInterface
{
    /**
     * Validate a value against validation rules
     * 
     * Implementations should:
     * - Sanitize the value (e.g., lowercase enums, normalize percentages)
     * - Return sanitized value on success for consistency
     * - Provide helpful error messages on failure
     * - Never throw exceptions - always return ValidationResult
     * 
     * @param mixed $value Value to validate (can be string, int, float, array, etc.)
     * @param array $config Optional runtime configuration for validation rules
     * 
     * @return ValidationResult Immutable result object with success status,
     *                          sanitized value, and error message (if failed)
     */
    public function validate($value, array $config = []): ValidationResult;
}
