<?php
/**
 * Immutable value object representing a post or taxonomy term.
 *
 * @package Postlinkly
 * @since   1.0.0
 */

declare(strict_types=1);

namespace Postlinkly\Post;

/**
 * Immutable value object representing a linkable item.
 *
 * Postlinkly treats WordPress posts and taxonomy terms as a single concept
 * called a "linkable item" — both can have inbound and outbound internal
 * links and both can be the source or target of a suggestion. The `$type`
 * field discriminates between the two.
 *
 * Properties are public for compactness; do not modify them after
 * construction. Helper methods produce modified copies when needed.
 *
 * @since 1.0.0
 */
final class PostModel {

	/**
	 * Linkable-item type: a regular WordPress post or post-type entry.
	 */
	public const TYPE_POST = 'post';

	/**
	 * Linkable-item type: a taxonomy term.
	 */
	public const TYPE_TERM = 'term';

	/**
	 * The item identifier (post ID or term ID).
	 *
	 * @var int
	 */
	public int $id;

	/**
	 * Item type: `post` or `term`. Always normalised in the constructor.
	 *
	 * @var string
	 */
	public string $type;

	/**
	 * Display title of the item. May be empty when the model is constructed
	 * from a partial dataset (e.g. a query that only fetched IDs).
	 *
	 * @var string
	 */
	public string $title;

	/**
	 * Publication status string (e.g. `publish`, `draft`). Empty when unknown.
	 *
	 * @var string
	 */
	public string $status;

	/**
	 * URL slug of the item. Empty when unknown.
	 *
	 * @var string
	 */
	public string $slug;

	/**
	 * @since 1.0.0
	 *
	 * @param int    $id     Post or term identifier.
	 * @param string $type   Optional. `post` or `term`. Default `post`.
	 *                       Any value other than `term` is normalised to `post`.
	 * @param string $title  Optional. Item title. Default empty.
	 * @param string $status Optional. Publication status. Default empty.
	 * @param string $slug   Optional. URL slug. Default empty.
	 */
	public function __construct(
		int $id,
		string $type = self::TYPE_POST,
		string $title = '',
		string $status = '',
		string $slug = ''
	) {
		$this->id     = $id;
		$this->type   = ( self::TYPE_TERM === $type ) ? self::TYPE_TERM : self::TYPE_POST;
		$this->title  = $title;
		$this->status = $status;
		$this->slug   = $slug;
	}

	/**
	 * Returns whether this item is a post (vs. a term).
	 *
	 * @since 1.0.0
	 *
	 * @return bool True when the item is a post.
	 */
	public function is_post(): bool {
		return self::TYPE_POST === $this->type;
	}

	/**
	 * Returns whether this item is a taxonomy term (vs. a post).
	 *
	 * @since 1.0.0
	 *
	 * @return bool True when the item is a term.
	 */
	public function is_term(): bool {
		return self::TYPE_TERM === $this->type;
	}

	/**
	 * Returns a stable composite key uniquely identifying this item.
	 *
	 * Useful when building lookup tables that contain both posts and terms.
	 * Format: `post:123` or `term:45`.
	 *
	 * @since 1.0.0
	 *
	 * @return string Composite key.
	 */
	public function get_key(): string {
		return $this->type . ':' . $this->id;
	}

	/**
	 * Returns a copy of this model with a different title.
	 *
	 * @since 1.0.0
	 *
	 * @param string $title The new title.
	 *
	 * @return self
	 */
	public function with_title( string $title ): self {
		return new self( $this->id, $this->type, $title, $this->status, $this->slug );
	}
}