<?php
/**
 * Localização de templates sobrescrevíveis pelo tema.
 *
 * @package ResgataPet
 */

namespace ResgataPet\Core;

defined( 'ABSPATH' ) || exit;

/**
 * Procura um template primeiro na pasta `resgata-pet/` do tema (filho e pai)
 * e, se não existir, usa o template neutro do plugin.
 */
final class TemplateLoader {

	public const THEME_DIR = 'resgata-pet';

	/**
	 * Caminho absoluto do template a usar.
	 *
	 * @param string $name Nome do arquivo, ex.: `animal-card.php`.
	 * @return string Caminho do arquivo ou string vazia se não existir.
	 */
	public static function locate( string $name ): string {
		$name = ltrim( $name, '/' );

		// Apenas nomes simples de arquivo: nada de subir diretórios.
		if ( ! preg_match( '/^[a-z0-9\-]+\.php$/', $name ) ) {
			return '';
		}

		$path = locate_template( self::THEME_DIR . '/' . $name );

		if ( ! $path ) {
			$path = RESGATA_PLUGIN_DIR . 'templates/' . $name;
		}

		/**
		 * Filtra o caminho do template do Resgata Pet.
		 *
		 * @param string $path Caminho absoluto do template.
		 * @param string $name Nome do arquivo de template.
		 */
		$path = (string) apply_filters( 'resgata_locate_template', $path, $name );

		return is_readable( $path ) ? $path : '';
	}

	/**
	 * Renderiza um template e devolve o HTML.
	 *
	 * @param string               $name Nome do arquivo de template.
	 * @param array<string, mixed> $args Variáveis disponíveis no template em `$resgata_args`.
	 */
	public static function render( string $name, array $args = array() ): string {
		$path = self::locate( $name );
		if ( '' === $path ) {
			return '';
		}

		ob_start();
		self::include_template( $path, $args );

		return (string) ob_get_clean();
	}

	/**
	 * Imprime um template. Cada template escapa os próprios valores.
	 *
	 * @param string               $name Nome do arquivo de template.
	 * @param array<string, mixed> $args Variáveis disponíveis no template em `$resgata_args`.
	 */
	public static function display( string $name, array $args = array() ): void {
		$path = self::locate( $name );
		if ( '' !== $path ) {
			self::include_template( $path, $args );
		}
	}

	/**
	 * Inclui o template em um escopo isolado.
	 *
	 * @param string               $resgata_path Caminho do template.
	 * @param array<string, mixed> $resgata_args Variáveis do template.
	 */
	private static function include_template( string $resgata_path, array $resgata_args ): void { // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.FoundAfterLastUsed -- Usada pelo template incluído.
		include $resgata_path;
	}
}