<?php
/**
 * File Path: includes/data/class-mbs-flat-taxonomy-seeder.php
 *
 * Flat Taxonomy Seeder — Parametric
 *
 * Reusable seeder for flat (non-hierarchical) WordPress taxonomies.
 * Eliminates structural duplication between MBS_Theme_Seeder and
 * MBS_Content_Warning_Seeder (D-004, Session 117).
 *
 * Usage:
 *   $seeder = new MBS_Flat_Taxonomy_Seeder(
 *       MBS_TAX_THEME,
 *       'mbs_themes_seeded',
 *       '1',
 *       array( 'Fantasy', 'Romance', ... )
 *   );
 *   $seeder->maybe_seed();
 *
 * @package    My_Book_Showroom
 * @subpackage Includes/Data
 * @since      1.1.0
 */

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

class MBS_Flat_Taxonomy_Seeder {

	/**
	 * Registered taxonomy slug to seed terms into.
	 *
	 * @var string
	 */
	private string $taxonomy;

	/**
	 * WordPress option key that records the completed seed version.
	 *
	 * @var string
	 */
	private string $seeded_option;

	/**
	 * Version string that marks the seed as complete.
	 * Bump to force a re-seed on the next load.
	 *
	 * @var string
	 */
	private string $seeded_version;

	/**
	 * Term display names to seed (not slugs).
	 *
	 * @var string[]
	 */
	private array $terms;

	/**
	 * Constructor.
	 *
	 * @param string   $taxonomy        Registered taxonomy slug.
	 * @param string   $seeded_option   wp_options key used to track seed state.
	 * @param string   $seeded_version  Version string; bump to force re-seed.
	 * @param string[] $terms           Display names to insert.
	 */
	public function __construct(
		string $taxonomy,
		string $seeded_option,
		string $seeded_version,
		array  $terms
	) {
		$this->taxonomy       = $taxonomy;
		$this->seeded_option  = $seeded_option;
		$this->seeded_version = $seeded_version;
		$this->terms          = $terms;
	}

	// -------------------------------------------------------------------------
	// Public API
	// -------------------------------------------------------------------------

	/**
	 * Seed only when the stored version is behind $seeded_version.
	 *
	 * @return void
	 */
	public function maybe_seed(): void {
		if ( get_option( $this->seeded_option ) === $this->seeded_version ) {
			return;
		}
		$this->seed();
	}

	/**
	 * Insert all default terms unconditionally.
	 *
	 * Safe to call multiple times — wp_insert_term() skips duplicates.
	 *
	 * @return void
	 */
	public function seed(): void {
		foreach ( $this->terms as $name ) {
			$this->insert_if_missing( $name );
		}
		update_option( $this->seeded_option, $this->seeded_version, false );
	}

	// -------------------------------------------------------------------------
	// Private helpers
	// -------------------------------------------------------------------------

	/**
	 * Insert a term if it does not already exist.
	 *
	 * @param string $name Term display name.
	 * @return void
	 */
	private function insert_if_missing( string $name ): void {
		$result = wp_insert_term( $name, $this->taxonomy );

		// 'term_exists' WP_Error is expected and safe to ignore.
		if ( is_wp_error( $result ) && 'term_exists' !== $result->get_error_code() ) {
			// Unexpected error (e.g. taxonomy not registered yet) — abort silently.
			return;
		}
	}
}
