<?php
/**
 * @package ACF
 * @author  WP Engine
 *
 * © 2026 Advanced Custom Fields (ACF®). All rights reserved.
 * "ACF" is a trademark of WP Engine.
 * Licensed under the GNU General Public License v2 or later.
 * https://www.gnu.org/licenses/gpl-2.0.html
 */

/**
 * Schema.org type and property data with lazy loading
 *
 * Data files in the /data directory are auto-generated by tools/generate-schema.js
 * To regenerate data files, run: npm run generate-schema
 *
 * @package ACF\AI\GEO
 */

namespace ACF\AI\GEO;

/**
 * Class SchemaData
 *
 * Contains static schema.org vocabulary data for type and property validation.
 * Data is lazy-loaded from separate files to reduce memory usage when not needed.
 */
class SchemaData {

	/**
	 * Type hierarchy mapping (lazy-loaded)
	 *
	 * @var array|null
	 */
	private static $type_hierarchy = null;

	/**
	 * Property domain mappings (lazy-loaded)
	 *
	 * @var array|null
	 */
	private static $property_domains = null;

	/**
	 * Property range mappings (lazy-loaded)
	 *
	 * @var array|null
	 */
	private static $property_ranges = null;

	/**
	 * Compatible properties by output type (lazy-loaded)
	 *
	 * @var array|null
	 */
	private static $compatible_properties = null;

	/**
	 * Get the type hierarchy mapping
	 *
	 * Maps each type to its parent type in the schema.org hierarchy.
	 * For example: 'Recipe' => 'HowTo'
	 *
	 * @since 6.8.0
	 *
	 * @return array
	 */
	public static function get_type_hierarchy(): array {
		if ( self::$type_hierarchy === null ) {
			self::$type_hierarchy = require __DIR__ . '/data/type-hierarchy.php';
		}
		return self::$type_hierarchy;
	}

	/**
	 * Get the property domain mappings
	 *
	 * Maps each property to the types it can be used with.
	 * For example: 'prepTime' => ['HowTo', 'HowToDirection']
	 *
	 * @since 6.8.0
	 *
	 * @return array
	 */
	public static function get_property_domains(): array {
		if ( self::$property_domains === null ) {
			self::$property_domains = require __DIR__ . '/data/property-domains.php';
		}
		return self::$property_domains;
	}

	/**
	 * Get the property range mappings
	 *
	 * Maps each property to the types it expects as values.
	 * For example: 'author' => ['Person', 'Organization']
	 *
	 * @since 6.8.0
	 *
	 * @return array
	 */
	public static function get_property_ranges(): array {
		if ( self::$property_ranges === null ) {
			self::$property_ranges = require __DIR__ . '/data/property-ranges.php';
		}
		return self::$property_ranges;
	}

	/**
	 * Get compatible properties by output type
	 *
	 * Pre-computed mapping of output types to compatible properties.
	 * For example: 'Text' => ['name', 'description', ...]
	 *
	 * @since 6.8.0
	 *
	 * @return array
	 */
	public static function get_compatible_properties(): array {
		if ( self::$compatible_properties === null ) {
			self::$compatible_properties = require __DIR__ . '/data/compatible-properties.php';
		}
		return self::$compatible_properties;
	}
}