<?php
/**
 * Feature Gate
 *
 * Central feature-flag helper for UGC Commerce.
 *
 * The free plugin ships with all the back-end code present but only activates
 * pro-tier feature classes when a gate check passes.  By default every gate
 * returns false.  The ugcify-pro plugin hooks into the filter and
 * returns true for features covered by the active license plan.
 *
 * Usage (in free plugin):
 *   if ( FeatureGate::is_enabled( 'customer_upload_form' ) ) { ... }
 *
 * Gate keys match the feature names defined in
 * UgcCommercePro\Utility\LicenseHelper::get_plan_features().
 *
 * Plan → features unlocked
 * ─────────────────────────────────────────────────────────────────────────────
 *  free (no license)
 *    • basic_reviews, basic_gallery, basic_moderation, seo_schema
 *
 *  growth ($99/yr)  — everything above +
 *    • customer_upload_form  (visitors can submit UGC)
 *    • product_tagging       (tag WooCommerce products in images)
 *    • social_import         (Instagram / TikTok / YouTube pull)
 *    • email_automation      (post-purchase review-request emails)
 *
 *  pro ($199/yr)  — everything above +
 *    • advanced_email_integration  (Mail Mint flows + coupon rewards)
 *    • reward_coupons              (coupon-based reward triggers)
 *
 *  business ($299/yr)  — everything above +
 *    • ab_testing             (A/B testing suite + conversion analytics)
 *    • advanced_gamification  (points, badges, leaderboards, checkout redemption)
 *
 * @package Ugcify\Helpers
 * @since   1.0.0
 */

namespace Ugcify\Helpers;

use Ugcify\License\LicenseHelper;

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

/**
 * Class FeatureGate
 */
class FeatureGate {

	/**
	 * Features that are always available without any license.
	 *
	 * @var string[]
	 */
	private static $free_features = array(
		'basic_reviews',
		'basic_gallery',
		'basic_moderation',
		'seo_schema',
	);

	/**
	 * Whether a given feature is currently enabled.
	 *
	 * Free-tier features always return true.
	 * All other features default to false unless the ugcify-pro plugin
	 * hooks in and returns true via the filter.
	 *
	 * @param string $feature Feature key (e.g. 'customer_upload_form').
	 * @return bool
	 */
	public static function is_enabled( string $feature ): bool {
		if ( in_array( $feature, self::$free_features, true ) ) {
			return true;
		}

		// Check the license directly — no pro plugin required.
		$value = LicenseHelper::is_feature_enabled( $feature );
		if ( false !== $value && null !== $value ) {
			return (bool) $value;
		}

		/**
		 * Filters whether a specific feature is currently enabled.
		 *
		 * The ugcify-pro plugin (if installed) can hook into this filter
		 * as a fallback override.
		 *
		 * @param bool   $enabled  Default false for paid features.
		 * @param string $feature  The feature key being checked.
		 */
		return (bool) apply_filters( 'ugcify_is_feature_enabled', false, $feature );
	}

	/**
	 * Return the minimum plan label that enables a feature for display purposes.
	 * Fires a filter so the pro plugin can supply the real plan name.
	 *
	 * @param string $feature
	 * @return string  e.g. 'Growth', 'Pro', 'Business'
	 */
	public static function required_plan( string $feature ): string {
		$tier = LicenseHelper::get_required_plan_for_feature( $feature );

		$labels = array(
			'free'     => 'Free',
			'growth'   => 'Growth',
			'pro'      => 'Pro',
			'business' => 'Business',
		);

		$label = isset( $labels[ $tier ] ) ? $labels[ $tier ] : 'Pro';

		/**
		 * Filters the human-readable plan label required for a feature.
		 *
		 * @param string $plan    Default label.
		 * @param string $feature Feature key.
		 */
		return (string) apply_filters( 'ugcify_feature_required_plan', $label, $feature );
	}
}
