<?php
/**
 * Database Version Manager
 *
 * Tracks database schema versions and plugin version changes.
 * Provides version comparison utilities.
 *
 * @package Wisewand
 * @since 1.0.2
 * @license GPL-2.0-or-later
 */

namespace Wisewand\Database;

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

/**
 * Database version tracker
 *
 * Manages schema version tracking and upgrade detection.
 *
 * @since 1.0.2
 */
class Database_Version {

	/**
	 * Option name for schema version
	 *
	 * @since 1.0.2
	 * @var string
	 */
	const SCHEMA_VERSION_OPTION = 'wisewand_db_schema_version';

	/**
	 * Option name for plugin version
	 *
	 * @since 1.0.2
	 * @var string
	 */
	const PLUGIN_VERSION_OPTION = 'wisewand_plugin_version';

	/**
	 * Option name for version history
	 *
	 * @since 1.0.2
	 * @var string
	 */
	const VERSION_HISTORY_OPTION = 'wisewand_version_history';

	/**
	 * Get current schema version
	 *
	 * Returns the currently installed database schema version.
	 *
	 * @since 1.0.2
	 * @return string|false Current schema version or false if not set.
	 */
	public static function get_current_version() {
		return get_option( self::SCHEMA_VERSION_OPTION, false );
	}

	/**
	 * Get latest schema version
	 *
	 * Returns the latest available schema version from Database_Schema.
	 *
	 * @since 1.0.2
	 * @return string Latest schema version.
	 */
	public static function get_latest_version() {
		return Database_Schema::get_version();
	}

	/**
	 * Update schema version
	 *
	 * Records the current schema version in database.
	 *
	 * @since 1.0.2
	 * @param string $version Schema version to record.
	 * @return bool True if version updated successfully.
	 */
	public static function update_version( $version ) {
		return update_option( self::SCHEMA_VERSION_OPTION, $version );
	}

	/**
	 * Check if schema upgrade needed
	 *
	 * Compares current version with latest version.
	 *
	 * @since 1.0.2
	 * @return bool True if upgrade needed.
	 */
	public static function needs_upgrade() {
		$current = self::get_current_version();
		$latest  = self::get_latest_version();

		// If no current version, this is a fresh install
		if ( false === $current ) {
			return false;
		}

		// Compare versions
		return version_compare( $current, $latest, '<' );
	}

	/**
	 * Get plugin version
	 *
	 * Returns the currently installed plugin version.
	 *
	 * @since 1.0.2
	 * @return string|false Current plugin version or false if not set.
	 */
	public static function get_plugin_version() {
		return get_option( self::PLUGIN_VERSION_OPTION, false );
	}

	/**
	 * Update plugin version
	 *
	 * Records the current plugin version in database.
	 *
	 * @since 1.0.2
	 * @param string $version Plugin version to record.
	 * @return bool True if version updated successfully.
	 */
	public static function update_plugin_version( $version ) {
		$old_version = self::get_plugin_version();

		// Record version change in history
		if ( $old_version && $old_version !== $version ) {
			self::record_version_update( $old_version, $version );
		}

		return update_option( self::PLUGIN_VERSION_OPTION, $version );
	}

	/**
	 * Check if plugin version changed
	 *
	 * Compares stored plugin version with current version constant.
	 *
	 * @since 1.0.2
	 * @return bool True if plugin version changed.
	 */
	public static function plugin_version_changed() {
		if ( ! defined( 'WISEWAND_PLUGIN_VERSION' ) ) {
			return false;
		}

		$current = self::get_plugin_version();

		// If no current version, this is a fresh install
		if ( false === $current ) {
			return true;
		}

		return $current !== WISEWAND_PLUGIN_VERSION;
	}

	/**
	 * Get version upgrade history
	 *
	 * Returns array of version upgrades with timestamps.
	 *
	 * @since 1.0.2
	 * @return array Version upgrade history.
	 */
	public static function get_version_history() {
		$history = get_option( self::VERSION_HISTORY_OPTION, array() );

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

		return $history;
	}

	/**
	 * Record version update in history
	 *
	 * Adds version upgrade to history with timestamp.
	 *
	 * @since 1.0.2
	 * @param string $from_version Previous version.
	 * @param string $to_version New version.
	 * @return bool True if history updated successfully.
	 */
	public static function record_version_update( $from_version, $to_version ) {
		$history = self::get_version_history();

		$history[] = array(
			'from'       => $from_version,
			'to'         => $to_version,
			'timestamp'  => current_time( 'mysql' ),
			'wp_version' => get_bloginfo( 'version' ),
		);

		// Keep only last 50 entries
		if ( count( $history ) > 50 ) {
			$history = array_slice( $history, -50 );
		}

		return update_option( self::VERSION_HISTORY_OPTION, $history );
	}

	/**
	 * Get version information summary
	 *
	 * Returns comprehensive version information for diagnostics.
	 *
	 * @since 1.0.2
	 * @return array Version information array.
	 */
	public static function get_version_info() {
		return array(
			'schema_version' => array(
				'current'       => self::get_current_version(),
				'latest'        => self::get_latest_version(),
				'needs_upgrade' => self::needs_upgrade(),
			),
			'plugin_version' => array(
				'current'  => self::get_plugin_version(),
				'constant' => defined( 'WISEWAND_PLUGIN_VERSION' ) ? WISEWAND_PLUGIN_VERSION : 'undefined',
				'changed'  => self::plugin_version_changed(),
			),
			'history'        => self::get_version_history(),
			'wp_version'     => get_bloginfo( 'version' ),
		);
	}

	/**
	 * Reset version tracking
	 *
	 * Clears all version tracking data.
	 * Used for testing or troubleshooting.
	 *
	 * @since 1.0.2
	 * @return bool True if reset successful.
	 */
	public static function reset_version_tracking() {
		delete_option( self::SCHEMA_VERSION_OPTION );
		delete_option( self::PLUGIN_VERSION_OPTION );
		delete_option( self::VERSION_HISTORY_OPTION );

		return true;
	}

	/**
	 * Initialize version tracking
	 *
	 * Sets up initial version tracking on plugin activation.
	 *
	 * @since 1.0.2
	 * @return bool True if initialization successful.
	 */
	public static function initialize() {
		// Set schema version
		if ( false === self::get_current_version() ) {
			self::update_version( Database_Schema::get_version() );
		}

		// Set plugin version
		if ( defined( 'WISEWAND_PLUGIN_VERSION' ) ) {
			if ( self::plugin_version_changed() ) {
				self::update_plugin_version( WISEWAND_PLUGIN_VERSION );
			}
		}

		return true;
	}
}
