<?php
/**
 * The field-reference string convention shared by the feed settings.
 *
 * @package Mapsemble
 */

namespace Mapsemble\Feed;

/**
 * Parses `tax:{taxonomy}` / `meta:{meta_key}` reference strings.
 *
 * Always-on filters, filter mappings and custom properties all point at
 * either a taxonomy or a meta key. They share this one parser so the stored
 * convention cannot drift between the boxes. Whether the referenced taxonomy
 * actually exists is the caller's concern — a reference can legitimately
 * outlive its taxonomy (plugin deactivated) and must still parse so the
 * admin screen can show it.
 */
final class FieldRef {

	public const KIND_TAX  = 'tax';
	public const KIND_META = 'meta';

	/**
	 * Parses a reference string.
	 *
	 * @param mixed $ref Raw reference, e.g. `tax:category` or `meta:_price`.
	 * @return array{kind: string, name: string}|null Null when malformed.
	 */
	public static function parse( $ref ): ?array {
		if ( ! is_string( $ref ) || '' === $ref ) {
			return null;
		}

		if ( str_starts_with( $ref, 'tax:' ) ) {
			$name = substr( $ref, 4 );
			// Taxonomy names are registered keys: lowercase alphanumerics,
			// underscores and hyphens.
			if ( ! preg_match( '/^[a-z0-9_-]+$/', $name ) ) {
				return null;
			}
			return array(
				'kind' => self::KIND_TAX,
				'name' => $name,
			);
		}

		if ( str_starts_with( $ref, 'meta:' ) ) {
			$name = substr( $ref, 5 );
			// Meta keys are case-sensitive and may start with an underscore;
			// refuse only whitespace and the impossible (postmeta.meta_key is
			// a varchar(255)).
			if ( '' === $name || strlen( $name ) > 255 || 1 === preg_match( '/\s/', $name ) ) {
				return null;
			}
			return array(
				'kind' => self::KIND_META,
				'name' => $name,
			);
		}

		return null;
	}
}