<?php
/**
 * Version bookkeeping and migrations.
 *
 * @package ElevenRank
 * @since   1.0.0
 */

namespace ElevenRank;

defined( 'ABSPATH' ) || exit;

/**
 * Records the installed version and runs ordered, idempotent migrations.
 *
 * Migrations only run in the admin and in cron, never on a front-end request.
 *
 * @since 1.0.0
 */
final class Upgrader {

	const VERSION_OPTION    = 'elevenrank_version';
	const DB_VERSION_OPTION = 'elevenrank_db_version';

	/**
	 * Version of the custom table schema. Bumped by the phases that add tables.
	 *
	 * @since 1.0.0
	 *
	 * @var int
	 */
	const DB_VERSION = 2;

	/**
	 * Runs pending migrations when the code is newer than the stored version.
	 *
	 * @since 1.0.0
	 *
	 * @return void
	 */
	public function maybe_upgrade(): void {
		if ( ! is_admin() && ! wp_doing_cron() ) {
			return;
		}

		$this->maybe_upgrade_database();

		$stored = get_option( self::VERSION_OPTION, '0' );

		if ( version_compare( is_string( $stored ) ? $stored : '0', ELEVENRANK_VERSION, '>=' ) ) {
			return;
		}

		foreach ( $this->migrations() as $version => $migration ) {
			if ( version_compare( is_string( $stored ) ? $stored : '0', (string) $version, '<' ) ) {
				call_user_func( $migration );
			}
		}

		$this->stamp_versions();
	}

	/**
	 * Creates or updates the custom tables when the stored schema version is older than the code's.
	 *
	 * Runs on its own, apart from the plugin version: a site that is new on a network where the plugin
	 * is active has the code but not the tables.
	 *
	 * @since 1.0.0
	 *
	 * @return void
	 */
	public function maybe_upgrade_database(): void {
		if ( Database::is_ready() ) {
			return;
		}

		Database::install();
		update_option( self::DB_VERSION_OPTION, self::DB_VERSION, true );
	}

	/**
	 * Records the current code and schema versions.
	 *
	 * @since 1.0.0
	 *
	 * @return void
	 */
	public function stamp_versions(): void {
		update_option( self::VERSION_OPTION, ELEVENRANK_VERSION );
		update_option( self::DB_VERSION_OPTION, self::DB_VERSION, true );
	}

	/**
	 * Migrations keyed by the version that introduced them, in ascending order.
	 *
	 * @since 1.0.0
	 *
	 * @return array<string, callable>
	 */
	private function migrations(): array {
		return array();
	}
}