<?php
/**
 * Validator Interface
 *
 * Defines the contract for validation classes throughout the plugin.
 * This interface ensures consistent validation behavior and error handling
 * across different input types and validation scenarios.
 *
 * @package     WPUltimateSecurity\UltimateSecurity\Contracts
 * @since       1.0.0
 * @author      Ultimate Security Team
 * @license     GPL-2.0-or-later
 */

declare(strict_types=1);

namespace WPUltimateSecurity\UltimateSecurity\Contracts;

/**
 * Interface ValidatorInterface
 *
 * Contract for all validation classes in the plugin. Validators are used to
 * ensure data integrity and security by validating user inputs, configuration
 * values, API requests, and other data before processing.
 *
 * Key principles:
 * - Validators should be stateless when possible
 * - Validation rules should be clearly defined and documented
 * - Error messages should be user-friendly and translatable
 * - Validators can be chained or composed for complex validation
 *
 * Example implementation:
 * ```php
 * class IpAddressValidator implements ValidatorInterface {
 *     private array $errors = [];
 *     private array $rules = [
 *         'format' => 'Valid IPv4 or IPv6 format',
 *         'not_private' => 'Cannot be a private IP address',
 *     ];
 *
 *     public function validate(mixed $value): bool {
 *         $this->errors = [];
 *
 *         if (!filter_var($value, FILTER_VALIDATE_IP)) {
 *             $this->errors[] = __('Invalid IP address format', 'ultimate-security');
 *             return false;
 *         }
 *         return true;
 *     }
 *
 *     public function getErrors(): array {
 *         return $this->errors;
 *     }
 *
 *     public function getRules(): array {
 *         return $this->rules;
 *     }
 * }
 * ```
 *
 * @since 1.0.0
 */
interface ValidatorInterface
{
    /**
     * Validate the given value against the validator's rules.
     *
     * Performs validation and returns a boolean indicating success or failure.
     * When validation fails, error messages are stored and can be retrieved
     * via getErrors().
     *
     * Implementation notes:
     * - Should clear any previous errors before validating
     * - Should handle null/empty values gracefully
     * - Should sanitize values before validation when appropriate
     * - Should use WordPress translation functions for error messages
     *
     * @since 1.0.0
     *
     * @param mixed $value The value to validate. Type depends on the specific validator.
     *
     * @return bool True if validation passes, false if any rule fails.
     */
    public function validate(mixed $value): bool;

    /**
     * Get all validation error messages from the last validation.
     *
     * Returns an array of human-readable error messages describing why
     * validation failed. The array is empty if validation passed or
     * if validate() has not been called yet.
     *
     * Error messages should be:
     * - User-friendly and understandable by non-technical users
     * - Translated using WordPress i18n functions
     * - Specific enough to guide the user in correcting the issue
     *
     * @since 1.0.0
     *
     * @return array<int, string> Array of error message strings, empty if no errors.
     */
    public function getErrors(): array;

    /**
     * Get the validation rules defined by this validator.
     *
     * Returns an associative array describing all validation rules that
     * this validator applies. This is useful for:
     * - Generating documentation
     * - Building UI hints and help text
     * - Debugging validation issues
     *
     * The format is typically:
     * ```php
     * [
     *     'rule_name' => 'Description of the rule',
     *     'min_length' => 'Must be at least 8 characters',
     *     'max_length' => 'Cannot exceed 255 characters',
     * ]
     * ```
     *
     * @since 1.0.0
     *
     * @return array<string, string> Associative array of rule names to descriptions.
     */
    public function getRules(): array;
}
