<?php
/**
 * Centralized helper for loading geographic data
 *
 * All public methods now delegate to SCPWOO_Geo_Repository.
 * This class is kept for backward compatibility with third-party code.
 *
 * @package AfriRegions
 * @deprecated Use SCPWOO_Geo_Repository directly.
 */

defined( 'ABSPATH' ) or die( 'Forbidden' );

class SCPWOO_Geo_Helper {

    /**
     * Get the list of allowed country codes.
     *
     * @deprecated Use SCPWOO_Geo_Repository::get_country_codes()
     * @return array List of country codes (e.g. ['CM', 'SN'])
     */
    public static function get_country_codes() {
        return SCPWOO_Geo_Repository::get_country_codes();
    }

    /**
     * Build a composite key: "CC:RC"
     *
     * @deprecated Use SCPWOO_Geo_Repository::composite_key()
     * @param string $country_code e.g. 'CM'
     * @param string $region_code  e.g. 'AD'
     * @return string e.g. 'CM:AD'
     */
    public static function composite_key( $country_code, $region_code ) {
        return SCPWOO_Geo_Repository::composite_key( $country_code, $region_code );
    }

    /**
     * Parse a composite key back to country + region.
     *
     * @deprecated Use SCPWOO_Geo_Repository::parse_key()
     * @param string $key e.g. 'CM:AD'
     * @return array [ 'country' => 'CM', 'region' => 'AD' ]
     */
    public static function parse_key( $key ) {
        return SCPWOO_Geo_Repository::parse_key( $key );
    }

    // =========================================================================
    // States (regions)
    // =========================================================================

    /**
     * Get raw regions indexed by country code.
     *
     * @deprecated Use SCPWOO_Geo_Repository::get_states_by_country()
     * @return array [ 'CM' => [ 'CE' => 'Centre', ... ], 'MG' => [...], ... ]
     */
    public static function get_states_by_country() {
        return SCPWOO_Geo_Repository::get_states_by_country();
    }

    /**
     * Get regions with composite keys (CC:RC => name).
     * Safe from collisions.
     *
     * @deprecated Compute from SCPWOO_Geo_Repository::get_states_by_country()
     * @return array [ 'CM:CE' => 'Centre', 'BF:CE' => 'Centre', ... ]
     */
    public static function get_states() {
        $by_country = self::get_states_by_country();
        $result = array();

        foreach ( $by_country as $cc => $regions ) {
            foreach ( $regions as $rc => $name ) {
                $result[ self::composite_key( $cc, $rc ) ] = $name;
            }
        }

        return $result;
    }

    /**
     * Find the country code that owns a region code.
     * If ambiguous, returns the first match.
     *
     * @deprecated Use SCPWOO_Geo_Repository::find_country_for_region()
     * @param string $region_code e.g. 'CE'
     * @return string e.g. 'CM'
     */
    public static function find_country_for_region( $region_code ) {
        return SCPWOO_Geo_Repository::find_country_for_region( $region_code );
    }

    /**
     * Find the country code that owns a city name.
     *
     * @deprecated Use SCPWOO_Geo_Repository::find_country_for_city()
     * @param string $city_name e.g. 'Douala'
     * @return string e.g. 'CM'
     */
    public static function find_country_for_city( $city_name ) {
        return SCPWOO_Geo_Repository::find_country_for_city( $city_name );
    }

    // =========================================================================
    // Places (cities) — country-indexed
    // =========================================================================

    /**
     * Get default cities indexed by country code.
     *
     * @deprecated Use SCPWOO_Geo_Repository::get_places_by_country()
     * @return array [ 'CM' => [ 'CE' => ['Yaoundé', ...], ... ], ... ]
     */
    public static function get_places_by_country() {
        return SCPWOO_Geo_Repository::get_places_by_country();
    }

    /**
     * Get default cities with composite keys (CC:RC => cities).
     * Safe from collisions.
     *
     * @deprecated Compute from SCPWOO_Geo_Repository::get_places_by_country()
     * @return array [ 'CM:CE' => ['Yaoundé', ...], 'MG:AD' => [...], ... ]
     */
    public static function get_default_places() {
        $by_country = self::get_places_by_country();
        $result = array();

        foreach ( $by_country as $cc => $regions ) {
            foreach ( $regions as $rc => $cities ) {
                $result[ self::composite_key( $cc, $rc ) ] = $cities;
            }
        }

        return $result;
    }

    // =========================================================================
    // Neighborhoods — country-indexed
    // =========================================================================

    /**
     * Get default neighborhoods indexed by country code.
     *
     * @deprecated Use SCPWOO_Geo_Repository::get_neighborhoods_by_country()
     * @return array [ 'CM' => [ 'Douala' => ['Akwa', ...], ... ], ... ]
     */
    public static function get_neighborhoods_by_country() {
        return SCPWOO_Geo_Repository::get_neighborhoods_by_country();
    }

    /**
     * Get default neighborhoods with composite keys (CC:city => hoods).
     *
     * @deprecated Compute from SCPWOO_Geo_Repository::get_neighborhoods_by_country()
     * @return array [ 'CM:Douala' => ['Akwa', ...], ... ]
     */
    public static function get_default_neighborhoods() {
        $by_country = self::get_neighborhoods_by_country();
        $result = array();

        foreach ( $by_country as $cc => $cities ) {
            foreach ( $cities as $city => $hoods ) {
                $result[ self::composite_key( $cc, $city ) ] = $hoods;
            }
        }

        return $result;
    }

    // =========================================================================
    // Merged data (with admin customizations) — country-indexed
    // =========================================================================

    /**
     * Merge default cities with admin customizations, indexed by country.
     *
     * @deprecated Use SCPWOO_Geo_Repository::get_merged_places_by_country()
     * @return array [ 'CM' => [ 'CE' => ['Yaoundé', ...], ... ], ... ]
     */
    public static function get_merged_places_by_country() {
        return SCPWOO_Geo_Repository::get_merged_places_by_country();
    }

    /**
     * Merge default neighborhoods with admin customizations, indexed by country.
     *
     * @deprecated Use SCPWOO_Geo_Repository::get_merged_neighborhoods_by_country()
     * @return array [ 'CM' => [ 'Douala' => ['Akwa', ...], ... ], ... ]
     */
    public static function get_merged_neighborhoods_by_country() {
        return SCPWOO_Geo_Repository::get_merged_neighborhoods_by_country();
    }

    /**
     * Invalidate merged data caches.
     *
     * @deprecated Use SCPWOO_Geo_Repository::invalidate_cache()
     */
    public static function invalidate_merged_cache(): void {
        SCPWOO_Geo_Repository::invalidate_cache();
    }

    /**
     * Register auto-invalidation hooks.
     * Call once during plugin init.
     */
    public static function register_cache_hooks(): void {
        add_action( 'update_option_' . SCPWOO_States_Places::OPTION_CUSTOM_PLACES, array( __CLASS__, 'invalidate_merged_cache' ) );
        add_action( 'update_option_' . SCPWOO_States_Places::OPTION_CUSTOM_HOODS, array( __CLASS__, 'invalidate_merged_cache' ) );
    }

    // =========================================================================
    // Backward-compatible flat merged (for single-country or non-critical uses)
    // =========================================================================

    /**
     * Get merged places as flat array (CC:RC => cities).
     * Use get_merged_places_by_country() for country-aware lookups.
     *
     * @deprecated Compute from SCPWOO_Geo_Repository::get_merged_places_by_country()
     * @return array [ 'CM:CE' => ['Yaoundé', ...], ... ]
     */
    public static function get_merged_places() {
        $by_country = self::get_merged_places_by_country();
        $result = array();
        foreach ( $by_country as $cc => $regions ) {
            foreach ( $regions as $rc => $cities ) {
                $result[ self::composite_key( $cc, $rc ) ] = $cities;
            }
        }
        return $result;
    }

    /**
     * Get merged neighborhoods as flat array (CC:city => hoods).
     *
     * @deprecated Compute from SCPWOO_Geo_Repository::get_merged_neighborhoods_by_country()
     * @return array [ 'CM:Douala' => ['Akwa', ...], ... ]
     */
    public static function get_merged_neighborhoods() {
        $by_country = self::get_merged_neighborhoods_by_country();
        $result = array();
        foreach ( $by_country as $cc => $cities ) {
            foreach ( $cities as $city => $hoods ) {
                $result[ self::composite_key( $cc, $city ) ] = $hoods;
            }
        }
        return $result;
    }

    // =========================================================================
    // Data file loading
    // =========================================================================

    /**
     * Include data files from a plugin subdirectory.
     *
     * Kept for backward compatibility — used by migration seeder.
     *
     * @param string $directory  Subdirectory name (e.g. 'places', 'neighborhoods', 'states').
     * @param string $global_var Name of the global variable used by data files.
     * @return array
     */
    private static function include_data_files( $directory, $global_var ) {
        global $$global_var;

        $backup      = isset( $$global_var ) ? $$global_var : null;
        $$global_var = array();
        $plugin_path = plugin_dir_path( SCPWOO_PLUGIN_FILE );

        $allowed_codes = self::get_country_codes();
        foreach ( $allowed_codes as $code ) {
            $file = $plugin_path . $directory . '/' . $code . '.php';
            if ( ! isset( ${$global_var}[ $code ] ) && file_exists( $file ) ) {
                include $file;
            }
        }

        $result      = is_array( $$global_var ) ? $$global_var : array();
        $$global_var = $backup;

        return $result;
    }

    // =========================================================================
    // Utilities
    // =========================================================================

    /**
     * Determine the source of an item (default or custom)
     *
     * @deprecated Use SCPWOO_Geo_Repository::get_item_source()
     * @param string $item     Name of the item to check.
     * @param array  $defaults List of plugin default items.
     * @return string 'default' if the item is part of the original file, 'custom' otherwise.
     */
    public static function get_item_source( $item, $defaults ) {
        return SCPWOO_Geo_Repository::get_item_source( $item, $defaults );
    }

    // =========================================================================
    // Input validation helpers
    // =========================================================================

    /**
     * Check if a country code is in the whitelist of allowed countries.
     *
     * @deprecated Use SCPWOO_Geo_Repository::is_valid_country()
     * @param string $cc Country code (e.g. 'CM').
     * @return bool
     */
    public static function is_valid_country( string $cc ): bool {
        return SCPWOO_Geo_Repository::is_valid_country( $cc );
    }

    /**
     * Check if a region code belongs to a given country.
     *
     * @deprecated Use SCPWOO_Geo_Repository::is_valid_region()
     * @param string $cc Country code.
     * @param string $rc Region code.
     * @return bool
     */
    public static function is_valid_region( string $cc, string $rc ): bool {
        return SCPWOO_Geo_Repository::is_valid_region( $cc, $rc );
    }

    /**
     * Check if a city belongs to a given country (any region).
     *
     * @deprecated Use SCPWOO_Geo_Repository::is_valid_city_in_country()
     * @param string $cc   Country code.
     * @param string $city City name.
     * @return bool
     */
    public static function is_valid_city_in_country( string $cc, string $city ): bool {
        return SCPWOO_Geo_Repository::is_valid_city_in_country( $cc, $city );
    }

    /**
     * Check if a city belongs to a specific region in a country.
     *
     * @deprecated Use SCPWOO_Geo_Repository::is_valid_city_in_region()
     * @param string $cc   Country code.
     * @param string $rc   Region code.
     * @param string $city City name.
     * @return bool
     */
    public static function is_valid_city_in_region( string $cc, string $rc, string $city ): bool {
        return SCPWOO_Geo_Repository::is_valid_city_in_region( $cc, $rc, $city );
    }
}
