<?php
/**
 * Catalogue of mappable source fields.
 *
 * @package FeedWeaver
 */

namespace FeedWeaver\Mapping;

defined( 'ABSPATH' ) || exit;

/**
 * Source identifiers are a closed list plus "meta:<key>".
 */
class Source_Catalog {

	const META_PREFIX = 'meta:';
	const TAX_PREFIX  = 'tax:';

	const CORE = array(
		'title',
		'permalink',
		'excerpt',
		'date',
		'modified',
		'author',
		'featured_image',
		'categories',
		'post_id',
		'guid',
		'featured_image_size',
		'featured_image_type',
		'none',
	);

	/** Sources whose value is a list (not usable as an attribute value). */
	const LIST_SOURCES = array( 'categories' );

	/**
	 * Whether a source identifier is structurally valid (policy for meta keys is checked separately).
	 *
	 * @param string $source Source identifier.
	 * @return bool
	 */
	public static function is_known( $source ): bool {
		if ( ! is_string( $source ) ) {
			return false;
		}
		return in_array( $source, self::CORE, true ) || self::is_meta( $source ) || self::is_taxonomy( $source );
	}

	/**
	 * Whether a taxonomy key is structurally valid. Whether the taxonomy exists
	 * and may be published is a WordPress question answered elsewhere.
	 *
	 * @param mixed $key Taxonomy key.
	 * @return bool
	 */
	public static function is_valid_taxonomy_key( $key ): bool {
		return is_string( $key ) && 1 === preg_match( '/^[a-z0-9_-]{1,32}$/D', $key );
	}

	/**
	 * Whether the source is a taxonomy ("tax:<taxonomy>").
	 *
	 * @param string $source Source identifier.
	 * @return bool
	 */
	public static function is_taxonomy( $source ): bool {
		return is_string( $source )
			&& 0 === strncmp( $source, self::TAX_PREFIX, strlen( self::TAX_PREFIX ) )
			&& self::is_valid_taxonomy_key( substr( $source, strlen( self::TAX_PREFIX ) ) );
	}

	/**
	 * Extracts the taxonomy key from a "tax:<taxonomy>" source.
	 *
	 * @param string $source Source identifier.
	 * @return string|null
	 */
	public static function taxonomy_name( $source ) {
		return self::is_taxonomy( $source ) ? substr( $source, strlen( self::TAX_PREFIX ) ) : null;
	}

	/**
	 * Whether a source yields a single text or number value, so it can fill an XML attribute:
	 * every source except lists (categories, taxonomies) and the value-less "none".
	 *
	 * @param mixed $source Source identifier.
	 * @return bool
	 */
	public static function is_scalar_source( $source ): bool {
		return self::is_known( $source ) && ! in_array( $source, self::LIST_SOURCES, true ) && 'none' !== $source && ! self::is_taxonomy( $source );
	}

	/**
	 * Whether the source is a custom field.
	 *
	 * @param string $source Source identifier.
	 * @return bool
	 */
	public static function is_meta( $source ): bool {
		return is_string( $source ) && 0 === strncmp( $source, self::META_PREFIX, strlen( self::META_PREFIX ) );
	}

	/**
	 * Extracts the meta key from a "meta:<key>" source.
	 *
	 * @param string $source Source identifier.
	 * @return string|null
	 */
	public static function meta_key( $source ) {
		return self::is_meta( $source ) ? substr( $source, strlen( self::META_PREFIX ) ) : null;
	}
}