<?php
/**
 * Webcasata FilterX Template Loader
 *
 * Handles locating and loading template files with theme override support.
 *
 * Override hierarchy (first match wins):
 *   1. {theme}/webcasata-filterx/{template-name}.php
 *   2. {child-theme}/webcasata-filterx/{template-name}.php  (handled automatically by locate_template)
 *   3. {plugin}/templates/{template-name}.php
 *
 * Example — to override the post card in your theme:
 *   Copy: wp-content/plugins/webcasata-filterx/templates/loop/card.php
 *   To:   wp-content/themes/your-theme/webcasata-filterx/loop/card.php
 *   Then edit freely. The plugin will never overwrite your file.
 *
 * @package Webcasata FilterX
 */

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

class FilterX_Template_Loader {

	/**
	 * Plugin's default templates directory (absolute path, with trailing slash).
	 *
	 * @var string
	 */
	private static $plugin_template_dir = '';

	/**
	 * Additional template directories registered by add-ons (e.g. Webcasata FilterX Pro).
	 * Each entry is checked after the theme but before the free plugin's own templates.
	 *
	 * @var string[]  Absolute paths with trailing slashes, keyed by plugin slug.
	 */
	private static $addon_template_dirs = array();

	/**
	 * Theme override folder name inside the active theme.
	 * e.g. wp-content/themes/my-theme/webcasata-filterx/
	 *
	 * Filterable via 'filterx_template_folder'.
	 *
	 * @var string
	 */
	private static $theme_template_folder = 'webcasata-filterx';

	/**
	 * Boot — called once from the main plugin file.
	 */
	public static function init() {
		self::$plugin_template_dir = FILTERX_PLUGIN_DIR . 'templates/';

		// Allow developers to rename the theme override folder
		self::$theme_template_folder = apply_filters( 'filterx_template_folder', 'webcasata-filterx' );
	}

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

	/**
	 * Register an additional template directory for an add-on plugin.
	 * Checked in registration order, after the theme but before the free plugin's templates.
	 *
	 * @param string $addon_slug  Unique identifier, e.g. 'webcasata-filterx-pro'.
	 * @param string $dir         Absolute path with trailing slash.
	 */
	public static function register_addon_template_dir( $addon_slug, $dir ) {
		self::$addon_template_dirs[ sanitize_key( $addon_slug ) ] = trailingslashit( $dir );
	}

	/**
	 * Locate a template file, checking the theme first.
	 *
	 * Priority:
	 *   1. Active theme  {theme}/webcasata-filterx/{template}
	 *   2. Add-on dirs   (registered by Pro or other add-ons, in order)
	 *   3. Free plugin   {plugin}/templates/{template}
	 *
	 * @param string $template_name  Relative path, e.g. 'loop/card.php'
	 * @return string                Absolute path to the template file.
	 */
	public static function locate( $template_name ) {
		$template_name = ltrim( $template_name, '/' );

		// 1. Check active theme (and parent theme automatically via locate_template)
		$theme_file = locate_template(
			array( trailingslashit( self::$theme_template_folder ) . $template_name ),
			false,   // do not load
			false    // do not require_once
		);

		if ( $theme_file ) {
			return $theme_file;
		}

		// 2. Add-on template directories (e.g. Pro plugin's templates/)
		foreach ( self::$addon_template_dirs as $addon_file_dir ) {
			$addon_file = $addon_file_dir . $template_name;
			if ( file_exists( $addon_file ) ) {
				return $addon_file;
			}
		}

		// 3. Fall back to plugin default
		$plugin_file = self::$plugin_template_dir . $template_name;

		if ( file_exists( $plugin_file ) ) {
			return $plugin_file;
		}

		// 4. Nothing found — return empty string, caller handles it
		return '';
	}

	/**
	 * Load (include) a template, optionally extracting variables into its scope.
	 *
	 * @param string $template_name  Relative path, e.g. 'loop/card.php'
	 * @param array  $args           Variables to extract into template scope.
	 * @param bool   $return         If true, return output as string instead of echoing.
	 * @return string|void
	 */
	public static function get_template( $template_name, $args = array(), $return = false ) {
		$located = self::locate( $template_name );

		if ( ! $located ) {
			/* translators: %s: template file name */
			_doing_it_wrong( __FUNCTION__, sprintf( esc_html__( 'Webcasata FilterX template "%s" not found.', 'webcasata-filterx' ), esc_html( $template_name ) ), '1.0.0' );
			return $return ? '' : null;
		}

		// Fire before-load action — allows developers to do setup
		do_action( 'filterx_before_template', $template_name, $located, $args );

		if ( $return ) {
			ob_start();
		}

		// Extract args safely — no variable overwrites of reserved names
		if ( ! empty( $args ) && is_array( $args ) ) {
			// phpcs:ignore WordPress.PHP.DontExtract.extract_extract
			extract( $args, EXTR_SKIP );
		}

		include $located; // phpcs:ignore WordPressVIPMinimum.Files.IncludingFile.UsingVariable

		do_action( 'filterx_after_template', $template_name, $located, $args );

		if ( $return ) {
			return ob_get_clean();
		}
	}

	/**
	 * Shorthand: get template output as a string.
	 *
	 * @param string $template_name
	 * @param array  $args
	 * @return string
	 */
	public static function get_template_html( $template_name, $args = array() ) {
		return (string) self::get_template( $template_name, $args, true );
	}

	/**
	 * Return an array of all overridable templates with their locations.
	 * Used by the admin "Template Status" panel.
	 *
	 * @return array[]  Each item: [ 'file', 'plugin_path', 'theme_path', 'overridden' ]
	 */
	public static function get_template_map() {
		$templates = array(
			'loop/loop.php',
			'loop/card.php',
			'loop/card-list.php',
			'loop/featured.php',
			'loop/no-results.php',
			'widget/wrapper.php',
			'widget/search-bar.php',
			'widget/filters.php',
			'pagination/numbers.php',
		);

		$map = array();

		foreach ( $templates as $tpl ) {
			$plugin_path = self::$plugin_template_dir . $tpl;
			$theme_file  = locate_template(
				array( trailingslashit( self::$theme_template_folder ) . $tpl ),
				false,
				false
			);

			$map[] = array(
				'file'        => $tpl,
				'plugin_path' => $plugin_path,
				'theme_path'  => $theme_file ?: '',
				'overridden'  => ! empty( $theme_file ),
				'resolved'    => ! empty( $theme_file ) ? $theme_file : $plugin_path,
			);
		}

		return $map;
	}

	/**
	 * Return the theme override directory path (for display in admin).
	 *
	 * @return string  e.g. "wp-content/themes/my-theme/webcasata-filterx/"
	 */
	public static function get_theme_template_dir_display() {
		$theme_root = str_replace( ABSPATH, '', get_stylesheet_directory() );
		return trailingslashit( $theme_root ) . trailingslashit( self::$theme_template_folder );
	}

	/**
	 * Absolute path to the theme's Webcasata FilterX template override directory.
	 *
	 * @return string  Absolute path, e.g. "/var/www/html/wp-content/themes/my-theme/webcasata-filterx/"
	 */
	public static function get_theme_template_dir_abs() {
		return trailingslashit( get_stylesheet_directory() ) . trailingslashit( self::$theme_template_folder );
	}

	/**
	 * Highlight search keywords in a string.
	 * Wraps matches in <mark class="filterx-highlight">.
	 *
	 * Proxy for the standalone filterx_highlight() function so templates
	 * can call either FilterX_Template_Loader::highlight() or filterx_highlight().
	 *
	 * @param string $text
	 * @param string $keyword
	 * @return string
	 */
	public static function highlight( $text, $keyword ) {
		return filterx_highlight( $text, $keyword );
	}
}