<?php
/**
 * Not Exists Operator.
 *
 * @package     Database
 * @subpackage  Operators
 * @copyright   2021-2026 - JJJ and all BerlinDB contributors
 * @license     https://opensource.org/licenses/MIT MIT
 * @since       3.0.0
 */

declare( strict_types = 1 );

namespace BerlinDB\Database\Operators;

defined( 'ABSPATH' ) || exit;

/**
 * NOT EXISTS operator — validates that a meta key does not exist.
 *
 * The NOT EXISTS check is implemented entirely by the Meta parser using a
 * LEFT JOIN + IS NULL pattern. This class returns an empty string from
 * get_value_sql() as a signal that there is no value fragment, which causes
 * get_sql() in the trait to return '' as well. Parsers guard against the
 * empty return with `! empty( $where )`.
 *
 * @since 3.0.0
 */
class NotExists extends Base {

	/**
	 * Human-readable name of this operator.
	 *
	 * @since 3.0.0
	 * @var string
	 */
	protected $name = 'Not Exists';

	/**
	 * SQL operator string used in comparisons (e.g. '=', 'IN', 'BETWEEN').
	 *
	 * @since 3.0.0
	 * @var string
	 */
	protected $compare = 'NOT EXISTS';

	/**
	 * Whether this is a positive (non-negating) operator.
	 *
	 * @since 3.0.0
	 * @var bool
	 */
	protected $positive = false;

	/**
	 * Whether this operator accepts multiple values (IN, BETWEEN).
	 *
	 * @since 3.0.0
	 * @var bool
	 */
	protected $multi = false;

	/**
	 * Whether this operator is intended for numeric comparisons (>, <, BETWEEN).
	 *
	 * @since 3.0.0
	 * @var bool
	 */
	protected $numeric = false;

	/**
	 * Returns an empty string — NOT EXISTS has no value fragment.
	 *
	 * The actual NOT EXISTS SQL is generated by the Meta parser via a LEFT JOIN
	 * combined with `{alias}.{column} IS NULL`. Returning '' here causes the
	 * trait's get_sql() to short-circuit and also return ''. Callers guard
	 * against the empty return with `! empty( $where )`.
	 *
	 * @since 3.0.0
	 *
	 * @param mixed  $value   Unused. Value is irrelevant for NOT EXISTS checks.
	 * @param string $pattern Unused.
	 *
	 * @return string Always empty string.
	 */
	public function get_value_sql( $value = null, $pattern = '%s' ) {

		// Nothing to prepare; NOT EXISTS has no value operand.
		return '';
	}
}
