<?php
/**
 * Feature Flags Manager
 *
 * Central place for the small number of runtime switches the plugin exposes
 * (Rules system availability, admin footer attribution). No licence, plan or
 * tier check lives here in the free distribution.
 *
 * @package Gatewell
 * @since 1.2.0
 */

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

/**
 * GATEWELL_Feature_Flags class.
 *
 * Manages the plugin's feature switches and their defaults.
 *
 * @since 1.2.0
 */
class GATEWELL_Feature_Flags {

	/**
	 * Check whether the Advanced Upload Rules system is enabled.
	 *
	 * Advanced Upload Rules is a standard, fully-functional part of the plugin.
	 * It is local logic with no external service or API cost, so it is enabled
	 * for every install and there is no licence, tier or plan check here.
	 *
	 * The only way to turn it off is the optional GATEWELL_ENABLE_RULES
	 * constant, which a site owner or host may define in wp-config.php to hide
	 * the Rules UI. When that constant is not defined, this always returns true.
	 *
	 * @since 1.2.0
	 * @return bool True if the Rules system is enabled (the default).
	 */
	public static function is_rules_enabled() {
		// Advanced Upload Rules is a free, fully-functional feature.
		// It is local logic with no external/API cost, so it ships enabled
		// for everyone. A developer may still force-disable it via the
		// GATEWELL_ENABLE_RULES constant if they don't want the UI.
		if ( defined( 'GATEWELL_ENABLE_RULES' ) ) {
			return (bool) GATEWELL_ENABLE_RULES;
		}

		return true;
	}

	/**
	 * Check if current user can access rules.
	 *
	 * @since 1.2.0
	 * @return bool True if user can access Rules System.
	 */
	public static function can_user_access_rules() {
		// Feature must be enabled first.
		if ( ! self::is_rules_enabled() ) {
			return false;
		}

		// If in admin-only mode, check capability.
		if ( get_option( 'gatewell_rules_admin_only', false ) ) {
			return current_user_can( 'manage_options' );
		}

		// Otherwise, anyone who can upload files can access.
		return current_user_can( 'upload_files' );
	}


	/**
	 * Check whether the plugin's own attribution footer should be rendered.
	 *
	 * Scope note (this changed in 1.5.3): attribution used to be rendered in the
	 * media upload modal, which is the WordPress media uploader — a core screen
	 * any author or editor passes through while doing unrelated work. That has
	 * been removed. The only remaining consumer is Admin_Page::render_footer(),
	 * which runs exclusively on this plugin's own admin screens (Dashboard,
	 * Settings, Metadata Scanner, System Info).
	 *
	 * Because that is an admin-facing area specific to this plugin, the
	 * attribution needs no admin opt-in and this returns true by default. There
	 * is deliberately no stored option behind it any more — a persisted
	 * "show branding" flag only made sense while the branding could appear on a
	 * core screen. Site owners who need it gone can return false from the
	 * `gatewell_show_branding` filter.
	 *
	 * @since 1.2.0
	 * @return bool True if the admin footer attribution should be shown.
	 */
	public static function show_branding() {
		/**
		 * Filter whether the Gatewell admin footer attribution is rendered.
		 *
		 * @since 1.5.3
		 * @param bool $show Whether to render the attribution. Default true.
		 */
		return (bool) apply_filters( 'gatewell_show_branding', true );
	}

	/**
	 * Get the URL the admin footer attribution links to.
	 *
	 * Defaults to the plugin author's site and is only ever used on this
	 * plugin's own admin pages. Filterable so white-label builds can point it at
	 * the agency that installed the plugin.
	 *
	 * @since 1.2.0
	 * @return string URL for the attribution link.
	 */
	public static function get_branding_url() {
		return apply_filters( 'gatewell_branding_url', 'https://www.danielneumann.com' );
	}


	/**
	 * Get the default upload form field configuration.
	 *
	 * Single source of truth — use this everywhere instead of redefining.
	 *
	 * @since 1.5.4
	 * @return array
	 */
	public static function get_form_field_defaults() {
		return array(
			'alt_text' => array( 'show' => true, 'required' => true ),
			'title'    => array( 'show' => true, 'required' => false ),
			'caption'  => array( 'show' => true, 'required' => false ),
		);
	}

	/**
	 * Get the default minimum character counts per field.
	 *
	 * Single source of truth — use this everywhere instead of redefining.
	 *
	 * @since 1.5.4
	 * @return array
	 */
	public static function get_field_minimum_defaults() {
		return array(
			'alt_text' => 5,
			'title'    => 5,
			'caption'  => 0,
		);
	}

	/**
	 * Register feature flag settings with WordPress Settings API.
	 *
	 * @since 1.2.0
	 */
	public static function register_settings() {
		/*
		 * gatewell_rules_admin_only is deliberately NOT registered.
		 *
		 * It has no form field on any settings tab, and wp-admin/options.php passes
		 * null to the sanitize callback of every registered option missing from
		 * $_POST and then saves the result — so registering it meant
		 * rest_sanitize_boolean( null ) === false was written back on every single
		 * settings save, silently switching admin-only mode off again.
		 *
		 * can_user_access_rules() reads it with get_option( ..., false ). Register it
		 * again only together with a field that renders it.
		 */
	}
}