<?php
/**
 * Database schema upgrader.
 *
 * Compares the installed DB schema version with the current version constant
 * and runs any pending upgrade routines in sequence.
 *
 * @package Robotstxt_Mlp2_Mlp5
 */

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Class Robotstxt_Mlp2_Mlp5_Db_Upgrader
 *
 * How to add a new schema version:
 *   1. Increment ROBOTSTXT_MLP2_MLP5_DB_VERSION in robotstxt-mlp2-mlp5.php (e.g. '1.1').
 *   2. Add a private static method upgrade_to_1_1() with the schema changes.
 *   3. Add a version_compare block for '1.1' inside maybe_upgrade().
 *   4. Update changelog.txt and CHANGELOG.md.
 */
class Robotstxt_Mlp2_Mlp5_Db_Upgrader {

	/**
	 * Run any pending DB upgrade routines.
	 *
	 * Reads the installed schema version from sitemeta and compares it with
	 * the ROBOTSTXT_MLP2_MLP5_DB_VERSION constant. If the installed version
	 * is lower, all intermediate upgrade methods are executed in order and
	 * the stored version is updated to the current value.
	 *
	 * Safe to call on every request — exits immediately when no upgrade is
	 * needed (one cached sitemeta read).
	 */
	public static function maybe_upgrade(): void {
		$installed = (string) get_site_option( Robotstxt_Mlp2_Mlp5_Logger::DB_VERSION_KEY, '0' );
		$current   = ROBOTSTXT_MLP2_MLP5_DB_VERSION;

		if ( version_compare( $installed, $current, '>=' ) ) {
			return;
		}

		// Execute upgrade routines in ascending version order.
		if ( version_compare( $installed, '1.0', '<' ) ) {
			self::upgrade_to_1_0();
		}

		// Future version upgrade blocks go here, following the same pattern above.

		update_site_option( Robotstxt_Mlp2_Mlp5_Logger::DB_VERSION_KEY, $current );
	}

	/**
	 * Upgrade DB schema to version 1.0.
	 *
	 * Creates the migration log table for the first time. dbDelta() is
	 * idempotent and handles both initial creation and incremental ALTER safely.
	 */
	private static function upgrade_to_1_0(): void {
		Robotstxt_Mlp2_Mlp5_Logger::create_table();
	}
}