<?php
/**
 * Centralized message accessor for AI Content by Parallax.
 *
 * Loads raw strings from messages-data.php and provides translated
 * access via get() / raw() / group() helpers.
 *
 * @package AIContentByParallax
 */

namespace AIContentByParallax\Config;

defined( 'ABSPATH' ) || exit;

/**
 * Provides translated and untranslated access to centralized message strings.
 */
class Messages {

	/**
	 * Cached messages array.
	 *
	 * @var array|null
	 */
	private static ?array $messages = null;

	/**
	 * Load messages from the data file (once).
	 *
	 * @return array
	 */
	private static function load(): array {
		if ( null === self::$messages ) {
			self::$messages = require __DIR__ . '/messages-data.php';
		}
		return self::$messages;
	}

	/**
	 * Get a translated message by dot-notation key.
	 *
	 * @param string $key Dot-notation key (e.g. 'notices.plugin_name').
	 * @return string Translated string, or the key itself if not found.
	 */
	public static function get( string $key ): string {
		$raw = self::resolve( $key );
		if ( null === $raw ) {
			if ( defined( 'WP_DEBUG' ) && WP_DEBUG ) {
				// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_trigger_error
				trigger_error( 'Messages: unknown key "' . esc_html( $key ) . '"', E_USER_NOTICE );
			}
			return $key;
		}
		return __( $raw, 'ai-content-by-parallax' ); // phpcs:ignore WordPress.WP.I18n.NonSingularStringLiteralText
	}

	/**
	 * Get a raw (untranslated) message by dot-notation key.
	 *
	 * Useful for sprintf format strings that are escaped by the caller.
	 * Returns an empty string (not the key) when the key is not found,
	 * since raw output is often used as a sprintf format string.
	 *
	 * @param string $key Dot-notation key.
	 * @return string Raw string, or empty string if key not found.
	 */
	public static function raw( string $key ): string {
		return self::resolve( $key ) ?? '';
	}

	/**
	 * Get a translated, sprintf-formatted message.
	 *
	 * Translates the format string first, then applies sprintf() so placeholders
	 * are resolved against the translated copy.
	 *
	 * @param string $key  Dot-notation key for the format string.
	 * @param mixed  ...$args Arguments passed to sprintf().
	 * @return string Translated and formatted string, or the key itself if not found.
	 */
	public static function format( string $key, mixed ...$args ): string {
		$raw = self::resolve( $key );
		if ( null === $raw ) {
			if ( defined( 'WP_DEBUG' ) && WP_DEBUG ) {
				// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_trigger_error
				trigger_error( 'Messages: unknown key "' . esc_html( $key ) . '"', E_USER_NOTICE );
			}
			return $key;
		}
		$format = __( $raw, 'ai-content-by-parallax' ); // phpcs:ignore WordPress.WP.I18n.NonSingularStringLiteralText
		return sprintf( $format, ...$args );
	}

	/**
	 * Get an entire group of translated messages.
	 *
	 * @param string $key Top-level key (e.g. 'js').
	 * @return array<string, string> Translated key => value pairs.
	 */
	public static function group( string $key ): array {
		$messages = self::load();
		if ( ! isset( $messages[ $key ] ) || ! is_array( $messages[ $key ] ) ) {
			return array();
		}

		$translated = array();
		foreach ( $messages[ $key ] as $sub_key => $value ) {
			$translated[ $sub_key ] = __( $value, 'ai-content-by-parallax' ); // phpcs:ignore WordPress.WP.I18n.NonSingularStringLiteralText
		}
		return $translated;
	}

	/**
	 * Resolve a dot-notation key to a raw string value.
	 *
	 * @param string $key Dot-notation key.
	 * @return string|null Raw value or null if not found.
	 */
	private static function resolve( string $key ): ?string {
		$messages = self::load();
		$parts    = explode( '.', $key, 2 );

		if ( count( $parts ) < 2 ) {
			return isset( $messages[ $key ] ) && is_string( $messages[ $key ] ) ? $messages[ $key ] : null;
		}

		[ $group, $sub_key ] = $parts;

		if ( isset( $messages[ $group ][ $sub_key ] ) && is_string( $messages[ $group ][ $sub_key ] ) ) {
			return $messages[ $group ][ $sub_key ];
		}

		return null;
	}
}