<?php
/**
 * Reference hint value object.
 *
 * @package Transtrix
 */

namespace Transtrix\Reference;

defined( 'ABSPATH' ) || exit;

/**
 * What kind of reference a meta key holds.
 *
 * A module author writes the string form ('post[]', 'attachment'); the walker
 * consumes the object form.
 */
class Reference_Hint {

	const TYPE_POST       = 'post';
	const TYPE_ATTACHMENT = 'attachment';
	const TYPE_TERM       = 'term';
	const TYPE_USER       = 'user';

	/**
	 * Reference type, one of the TYPE_* constants.
	 *
	 * @var string
	 */
	private $type;

	/**
	 * Whether the meta value holds many ids rather than one.
	 *
	 * @var bool
	 */
	private $is_list;

	/**
	 * Taxonomy a term hint is confined to, or '' for none.
	 *
	 * A bare `term` would match any term id in the map, and ids collide across
	 * taxonomies: WP Travel Engine's pricing category 2 and its `trip_tag`
	 * term 2 are different things that happen to share a number. Naming the
	 * taxonomy is what stops one being rewritten into the other.
	 *
	 * @var string
	 */
	private $taxonomy = '';

	/**
	 * Constructor.
	 *
	 * @param string $type     Reference type.
	 * @param bool   $is_list  Whether the value holds a list of ids.
	 * @param string $taxonomy Taxonomy a term hint is confined to, or ''.
	 */
	public function __construct( string $type, bool $is_list = false, string $taxonomy = '' ) {
		$this->type     = $type;
		$this->is_list  = $is_list;
		$this->taxonomy = $taxonomy;
	}

	/**
	 * Build from the string form a module author writes.
	 *
	 * @param string $notation For example 'post[]' or 'attachment'.
	 * @return Reference_Hint|null Null when the type is not recognised.
	 */
	public static function from( string $notation ): ?Reference_Hint {
		$is_list  = ( '[]' === substr( $notation, -2 ) );
		$type     = $is_list ? substr( $notation, 0, -2 ) : $notation;
		$taxonomy = '';

		// term:trip-packages-categories confines a term hint to one taxonomy.
		if ( false !== strpos( $type, ':' ) ) {
			list( $type, $taxonomy ) = explode( ':', $type, 2 );
		}

		$known = array(
			self::TYPE_POST,
			self::TYPE_ATTACHMENT,
			self::TYPE_TERM,
			self::TYPE_USER,
		);

		if ( ! in_array( $type, $known, true ) ) {
			return null;
		}

		if ( '' !== $taxonomy && self::TYPE_TERM !== $type ) {
			return null;
		}

		return new self( $type, $is_list, $taxonomy );
	}

	/**
	 * The reference type.
	 *
	 * @return string
	 */
	public function type(): string {
		return $this->type;
	}

	/**
	 * Whether the value holds a list of ids.
	 *
	 * @return bool
	 */
	public function is_list(): bool {
		return $this->is_list;
	}

	/**
	 * The object type used as the Id_Map bucket.
	 *
	 * Attachments are posts: an attachment id and a post id share one id space,
	 * so they must share one map bucket or a remap silently misses.
	 *
	 * @return string
	 */
	public function map_bucket(): string {
		if ( self::TYPE_ATTACHMENT === $this->type ) {
			return self::TYPE_POST;
		}

		if ( self::TYPE_TERM === $this->type && '' !== $this->taxonomy ) {
			return self::TYPE_TERM . ':' . $this->taxonomy;
		}

		return $this->type;
	}

	/**
	 * Whether an id this hint cannot resolve is worth telling the user about.
	 *
	 * A post id that is not in the package is a broken link: a post is only
	 * ever referenced on purpose. A taxonomy-scoped term id is different — it
	 * shares its number space with plain local keys. WP Travel Engine prices a
	 * package against ids that are sometimes `trip-packages-categories` terms
	 * and sometimes just keys, and the export already decided which by
	 * carrying only the real terms. An id that is not in the map is therefore
	 * not a term that went missing; it was never a reference. Warning about it
	 * would bury the real warnings under noise.
	 *
	 * @return bool
	 */
	public function reports_unresolved(): bool {
		return ! ( self::TYPE_TERM === $this->type && '' !== $this->taxonomy );
	}

	/**
	 * The taxonomy this hint is confined to, or '' when it is not.
	 *
	 * @return string
	 */
	public function taxonomy(): string {
		return $this->taxonomy;
	}
}