<?php
/**
 * Typed access to the plugin's options.
 *
 * @package Kordiam
 */

declare( strict_types=1 );

namespace Kordiam\Support;

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

/**
 * The one place in the plugin that knows the option prefix; callers pass unprefixed keys.
 *
 * Reads fall back to the Desk-Net option; writes never touch legacy names, so reverting stays possible.
 */
final class Options {

	/**
	 * Prefix every option name carries.
	 *
	 * @var string
	 */
	public const PREFIX = 'kordiam_';

	/**
	 * Sentinel distinguishing "option absent" from "option holds a falsy value".
	 *
	 * @var string
	 */
	private const MISSING = "\0kordiam-missing\0";

	/**
	 * Option recording the keys that were deliberately cleared.
	 *
	 * Stops the Desk-Net fallback from resurrecting a deleted value; set() removes the marker.
	 *
	 * @var string
	 */
	private const CLEARED_KEYS = 'cleared_keys';

	/**
	 * Blocking instantiation: this class is a namespaced function group.
	 */
	private function __construct() {
	}

	/**
	 * Building the storage name for a key.
	 *
	 * @param string $key Unprefixed option key.
	 *
	 * @return string Full option name.
	 */
	public static function name( string $key ): string {
		return self::PREFIX . $key;
	}

	/**
	 * Reading an option, falling back to its Desk-Net ancestor.
	 *
	 * @param string $key           Unprefixed option key.
	 * @param mixed  $default_value Returned when neither name is stored.
	 *
	 * @return mixed Stored value, or the default.
	 */
	public static function get( string $key, $default_value = null ) {
		$value = get_option( self::name( $key ), self::MISSING );

		if ( self::MISSING !== $value ) {
			return $value;
		}

		$legacy_name = LegacyKeyMap::to_legacy_option( $key );

		if ( null === $legacy_name || self::was_cleared( $key ) ) {
			return $default_value;
		}

		$legacy_value = get_option( $legacy_name, self::MISSING );

		return self::MISSING === $legacy_value ? $default_value : $legacy_value;
	}

	/**
	 * Checking whether a key was deliberately cleared.
	 *
	 * Public for LegacyDataImporter, which must not copy a cleared key back either.
	 *
	 * @param string $key Unprefixed option key.
	 *
	 * @return bool Whether a delete marked this key as cleared.
	 */
	public static function was_cleared( string $key ): bool {
		return in_array( $key, self::cleared_keys(), true );
	}

	/**
	 * Reading the list of deliberately cleared keys.
	 *
	 * @return string[] Unprefixed option keys.
	 */
	private static function cleared_keys(): array {
		$stored = get_option( self::name( self::CLEARED_KEYS ), array() );

		if ( ! is_array( $stored ) ) {
			return array();
		}

		$keys = array();

		foreach ( $stored as $key ) {
			if ( is_string( $key ) ) {
				$keys[] = $key;
			}
		}

		return $keys;
	}

	/**
	 * Recording, or forgetting, that a key was deliberately cleared.
	 *
	 * Only keys with a Desk-Net fallback need a marker.
	 *
	 * @param string $key     Unprefixed option key.
	 * @param bool   $cleared Whether the key is now cleared.
	 */
	private static function mark_cleared( string $key, bool $cleared ): void {
		if ( self::CLEARED_KEYS === $key || null === LegacyKeyMap::to_legacy_option( $key ) ) {
			return;
		}

		$keys    = self::cleared_keys();
		$present = in_array( $key, $keys, true );

		if ( $cleared === $present ) {
			return;
		}

		if ( $cleared ) {
			$keys[] = $key;
		} else {
			$keys = array_values( array_diff( $keys, array( $key ) ) );
		}

		update_option( self::name( self::CLEARED_KEYS ), $keys, false );
	}

	/**
	 * Reading an option as a trimmed string.
	 *
	 * @param string $key           Unprefixed option key.
	 * @param string $default_value Returned when the option is absent or an array.
	 *
	 * @return string Stored value cast to string.
	 */
	public static function get_string( string $key, string $default_value = '' ): string {
		$value = self::get( $key );

		if ( is_scalar( $value ) ) {
			return trim( (string) $value );
		}

		return $default_value;
	}

	/**
	 * Reading an option as an integer.
	 *
	 * @param string $key           Unprefixed option key.
	 * @param int    $default_value Returned when the option is absent or non-numeric.
	 *
	 * @return int Stored value cast to int.
	 */
	public static function get_int( string $key, int $default_value = 0 ): int {
		$value = self::get( $key );

		return is_numeric( $value ) ? (int) $value : $default_value;
	}

	/**
	 * Reading an option as a boolean.
	 *
	 * Checkbox settings are stored by the Settings API as '1', 'on' or an empty
	 * string, so a plain cast is not enough.
	 *
	 * @param string $key           Unprefixed option key.
	 * @param bool   $default_value Returned when the option is absent.
	 *
	 * @return bool Stored value interpreted as a flag.
	 */
	public static function get_bool( string $key, bool $default_value = false ): bool {
		$value = self::get( $key, self::MISSING );

		if ( self::MISSING === $value ) {
			return $default_value;
		}

		if ( is_string( $value ) ) {
			return ! in_array( strtolower( trim( $value ) ), array( '', '0', 'false', 'off', 'no' ), true );
		}

		return (bool) $value;
	}

	/**
	 * Reading an option as an array.
	 *
	 * @param string       $key           Unprefixed option key.
	 * @param array<mixed> $default_value Returned when the option is absent or not an array.
	 *
	 * @return array<mixed> Stored value.
	 */
	public static function get_array( string $key, array $default_value = array() ): array {
		$value = self::get( $key );

		return is_array( $value ) ? $value : $default_value;
	}

	/**
	 * Writing an option under the Kordiam prefix.
	 *
	 * Pass $autoload false for anything bulky (e.g. API lists) or secret.
	 *
	 * @param string    $key      Unprefixed option key.
	 * @param mixed     $value    Value to store.
	 * @param bool|null $autoload Whether to load the value on every request; null for core's default.
	 *
	 * @return bool Whether the value changed.
	 */
	public static function set( string $key, $value, ?bool $autoload = null ): bool {
		self::mark_cleared( $key, false );

		return update_option( self::name( $key ), $value, $autoload );
	}

	/**
	 * Deleting an option.
	 *
	 * Only the Kordiam name is removed; the Desk-Net original is left alone.
	 *
	 * @param string $key Unprefixed option key.
	 *
	 * @return bool Whether the option existed and was removed.
	 */
	public static function delete( string $key ): bool {
		$deleted = delete_option( self::name( $key ) );

		self::mark_cleared( $key, true );

		return $deleted;
	}

	/**
	 * Checking whether a Kordiam value is stored, ignoring any legacy fallback.
	 *
	 * @param string $key Unprefixed option key.
	 *
	 * @return bool Whether the Kordiam option exists.
	 */
	public static function exists( string $key ): bool {
		return self::MISSING !== get_option( self::name( $key ), self::MISSING );
	}

	/**
	 * Checking an option against the "do not import" marker.
	 *
	 * Accepts the label form too, which legacy sites may have stored.
	 *
	 * @param string $key Unprefixed option key.
	 *
	 * @return bool Whether the mapping says to skip the item.
	 */
	public static function is_do_not_import( string $key ): bool {
		$value = strtolower( self::get_string( $key ) );

		return Config::DO_NOT_IMPORT === $value || 'do not import' === $value;
	}

	/**
	 * Checking an option against the "no sync" marker.
	 *
	 * @param string $key Unprefixed option key.
	 *
	 * @return bool Whether the mapping says to leave the field untouched.
	 */
	public static function is_no_sync( string $key ): bool {
		$value = strtolower( self::get_string( $key ) );

		return Config::NO_SYNC === $value || 'no sync' === $value;
	}
}