<?php
/**
 * File Path: includes/migrations/interface-mbs-migration.php
 *
 * MBS_Migration — DB Installer Refactor
 *
 * Contract for all versioned database migration objects.
 * Each migration is responsible for exactly one schema version bump.
 * Migrations are instantiated by MBS_DB_Installer::get_migrations() and
 * executed in ascending version order by MBS_DB_Installer::maybe_migrate().
 * All implementations must be idempotent — safe to run more than once.
 *
 * @package MyBookShowroom
 * @since   3.2.0
 */

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

/**
 * Interface MBS_Migration
 *
 * Versioned database migration contract.
 * Implement this interface in includes/migrations/class-mbs-migration-X-X.php,
 * then append a new instance to MBS_DB_Installer::get_migrations().
 */
interface MBS_Migration { // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedInterfaceFound -- mbs_/MBS_ prefix is correct; scanner not configured with plugin prefix

	/**
	 * Returns the schema version this migration upgrades to.
	 *
	 * Must match the corresponding mbs_db_version string stored in wp_options.
	 *
	 * @return string Semantic version string, e.g. '1.3'.
	 */
	public function version(): string;

	/**
	 * Executes the migration.
	 *
	 * Must be idempotent — running it more than once must not corrupt data.
	 * Only called when the stored mbs_db_version is less than version().
	 *
	 * @global wpdb $wpdb WordPress database abstraction object.
	 * @return void
	 */
	public function up(): void;
}
