<?php
/**
 * Schedule Validator Utility
 *
 * Provides validation functions for RSS scheduling feature.
 * Validates schedule modes, publish modes, and time formats.
 *
 * @package Wisewand
 * @since 2.1.3
 * @license GPL-2.0-or-later
 */

namespace Wisewand\Utils;

// Exit if accessed directly.
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Schedule validation utilities
 *
 * Centralized validation for RSS scheduling parameters.
 * Implements whitelist approach for all enums.
 *
 * @since 2.1.3
 */
class Schedule_Validator {

	/**
	 * Valid schedule modes
	 *
	 * @since 2.1.3
	 * @var array
	 */
	const VALID_SCHEDULE_MODES = array( 'inherit', 'custom' );

	/**
	 * Valid publish modes
	 *
	 * @since 2.1.3
	 * @var array
	 */
	const VALID_PUBLISH_MODES = array( 'immediate', 'draft', 'scheduled' );

	/**
	 * Validate schedule mode
	 *
	 * Checks if schedule mode is in whitelist.
	 * Used for per-feed schedule mode validation.
	 *
	 * @since 2.1.3
	 * @param string $mode Schedule mode to validate.
	 * @return bool True if valid.
	 */
	public static function validate_schedule_mode( $mode ) {
		return in_array( $mode, self::VALID_SCHEDULE_MODES, true );
	}

	/**
	 * Validate publish mode
	 *
	 * Checks if publish mode is in whitelist.
	 * Used for global publish mode validation.
	 *
	 * @since 2.1.3
	 * @param string $mode Publish mode to validate.
	 * @return bool True if valid.
	 */
	public static function validate_publish_mode( $mode ) {
		return in_array( $mode, self::VALID_PUBLISH_MODES, true );
	}

	/**
	 * Validate time format (HH:MM or HH:MM:SS)
	 *
	 * Validates 24-hour time format.
	 * Accepts both HH:MM and HH:MM:SS formats.
	 *
	 * Valid examples:
	 * - "09:00" (9 AM)
	 * - "14:30" (2:30 PM)
	 * - "23:59" (11:59 PM)
	 * - "11:30:00" (11:30 AM with seconds)
	 *
	 * @since 2.1.3
	 * @param string $time Time string to validate.
	 * @return bool True if valid.
	 */
	public static function validate_time_format( $time ) {
		// Pattern: HH:MM or HH:MM:SS
		// Hours: 00-23, Minutes/Seconds: 00-59
		return (bool) preg_match( '/^([01][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$/', $time );
	}

	/**
	 * Convert HH:MM to HH:MM:SS format
	 *
	 * Ensures time is in database-compatible format.
	 * Adds :00 seconds if not present.
	 *
	 * @since 2.1.3
	 * @param string $time Time in HH:MM or HH:MM:SS format.
	 * @return string Time in HH:MM:SS format.
	 */
	public static function normalize_time( $time ) {
		// If already has seconds, return as-is
		if ( substr_count( $time, ':' ) === 2 ) {
			return $time;
		}

		// Add seconds
		return $time . ':00';
	}

	/**
	 * Get valid schedule modes
	 *
	 * Returns array of valid schedule modes.
	 * Useful for UI generation and filtering.
	 *
	 * @since 2.1.3
	 * @return array Valid schedule modes.
	 */
	public static function get_valid_schedule_modes() {
		/**
		 * Filter valid schedule modes
		 *
		 * Allows extensions to add custom schedule modes.
		 *
		 * @since 2.1.3
		 * @param array $modes Array of valid schedule mode strings.
		 */
		return apply_filters( 'wisewand_valid_schedule_modes', self::VALID_SCHEDULE_MODES );
	}

	/**
	 * Get valid publish modes
	 *
	 * Returns array of valid publish modes.
	 * Useful for UI generation and filtering.
	 *
	 * @since 2.1.3
	 * @return array Valid publish modes.
	 */
	public static function get_valid_publish_modes() {
		/**
		 * Filter valid publish modes
		 *
		 * Allows extensions to add custom publish modes.
		 *
		 * @since 2.1.3
		 * @param array $modes Array of valid publish mode strings.
		 */
		return apply_filters( 'wisewand_valid_publish_modes', self::VALID_PUBLISH_MODES );
	}
}
