<?php
/**
 * Interface for all email conditions.
 *
 * Every condition class must implement this interface to be registered
 * in the ConditionRegistry and evaluated by the LogicalExpression engine.
 *
 * The evaluate() method receives the comparison operator as a parameter,
 * allowing conditions to handle equality (=), inequality (!=), and
 * ordering operators (>, >=, <, <=) as appropriate for their data type.
 *
 * @package     EDD\Pro\Emails\ConditionalTags\Conditions
 * @copyright   Copyright (c) 2026, Sandhills Development, LLC
 * @license     https://opensource.org/licenses/gpl-2.0.php GNU Public License
 * @since       3.6.6
 */

namespace EDD\Pro\Emails\ConditionalTags\Conditions;

// Exit if accessed directly.
defined( 'ABSPATH' ) || exit; // @codeCoverageIgnore

/**
 * Interface ConditionInterface
 *
 * @since 3.6.6
 */
interface ConditionInterface {

	/**
	 * Get the unique key for this condition.
	 *
	 * This key is used to match the condition name in the expression
	 * (e.g. 'gateway' in {if gateway="stripe"}).
	 *
	 * @since 3.6.6
	 *
	 * @return string Condition key.
	 */
	public function get_key();

	/**
	 * Get the human-readable label for this condition.
	 *
	 * @since 3.6.6
	 *
	 * @return string Condition label.
	 */
	public function get_label();

	/**
	 * Get the comparison operators supported by this condition.
	 *
	 * @since 3.6.6
	 *
	 * @return string[] Supported operators.
	 */
	public function get_supported_operators();

	/**
	 * Get the email contexts supported by this condition.
	 *
	 * Return an empty array when the condition is allowed in all contexts.
	 *
	 * @since 3.6.6
	 *
	 * @return string[] Supported contexts.
	 */
	public function get_supported_contexts();

	/**
	 * Get the UI input type descriptor for the value field.
	 *
	 * Returns an array with at minimum a 'type' key. Supported types:
	 * 'text', 'date', 'select', 'number', 'hidden'.
	 *
	 * The 'select' type must also include an 'options' key containing
	 * an array of value/label pairs.
	 *
	 * @since 3.6.6
	 *
	 * @return array{type: string, options?: array} UI input type descriptor.
	 */
	public function get_ui_input_type();

	/**
	 * Evaluate the condition for a given order, operator, value, and context.
	 *
	 * The operator parameter indicates how the comparison should be performed:
	 *   - '='  : The actual value equals the expected value.
	 *   - '!=' : The actual value does not equal the expected value.
	 *   - '>'  : The actual value is greater than the expected value.
	 *   - '>=' : The actual value is greater than or equal to the expected value.
	 *   - '<'  : The actual value is less than the expected value.
	 *   - '<=' : The actual value is less than or equal to the expected value.
	 *
	 * Conditions that only support equality/inequality (e.g. string conditions
	 * like gateway or username) should return false for ordering operators.
	 *
	 * @since 3.6.6
	 *
	 * @param int    $object_id  The EDD object ID (e.g. order ID).
	 * @param object $edd_object The EDD object (e.g. Order instance).
	 * @param object $email      The EDD email object.
	 * @param mixed  $value      The expected value to compare against.
	 * @param string $operator   The comparison operator (=, !=, >, >=, <, <=).
	 * @param mixed  $context    Additional contextual data for evaluation.
	 * @return bool True if the condition passes, false otherwise.
	 */
	public function evaluate( $object_id, $edd_object, $email, $value, $operator = '=', $context = '' );
}
