<?php
/**
 * Immutable value object representing a keyword.
 *
 * @package Postlinkly
 * @since   1.0.0
 */

declare(strict_types=1);

namespace Postlinkly\Keywords;

/**
 * Immutable value object representing a keyword associated with a post.
 *
 * Used both for target keywords (focus keywords sourced from SEO plugins or
 * entered manually) and auto-link rule keywords. The `$source` field
 * discriminates between sources (`yoast`, `rankmath`, `aioseo`, `seopress`,
 * `squirrly`, `manual`, `auto-link`).
 *
 * Stemmed and accent-normalised forms are computed by a separate factory
 * (Stage 6) and passed to the constructor — this class is data-only.
 *
 * Properties are public for compactness; do not modify them after
 * construction.
 *
 * @since 1.0.0
 */
final class KeywordModel {

	/**
	 * Database row identifier (zero when not persisted).
	 *
	 * @var int
	 */
	public int $row_id;

	/**
	 * Owning post or term identifier.
	 *
	 * @var int
	 */
	public int $post_id;

	/**
	 * Owning item type (`post` or `term`).
	 *
	 * @var string
	 */
	public string $post_type;

	/**
	 * Source identifier — see class description for accepted values.
	 *
	 * @var string
	 */
	public string $source;

	/**
	 * Raw keyword phrase as entered or imported.
	 *
	 * @var string
	 */
	public string $phrase;

	/**
	 * Stemmed form of the phrase (lowercase, stems applied per locale).
	 *
	 * @var string
	 */
	public string $stemmed;

	/**
	 * Accent-stripped + stemmed form. Used to match against accent-free
	 * variants common in URLs and slugs.
	 *
	 * @var string
	 */
	public string $normalized;

	/**
	 * Word count of the phrase. Single-word matches and multi-word matches
	 * are scored differently downstream.
	 *
	 * @var int
	 */
	public int $word_count;

	/**
	 * Whether the keyword has been verified (e.g. user-confirmed for GSC).
	 *
	 * @var bool
	 */
	public bool $checked;

	/**
	 * GSC impression count for this keyword (zero when unavailable).
	 *
	 * @var int
	 */
	public int $impressions;

	/**
	 * GSC click count for this keyword (zero when unavailable).
	 *
	 * @var int
	 */
	public int $clicks;

	/**
	 * @since 1.0.0
	 *
	 * @param int    $post_id     Owning post/term identifier.
	 * @param string $post_type   Owning item type (`post` or `term`).
	 * @param string $source      Source identifier (e.g. `yoast`, `manual`).
	 * @param string $phrase      Raw keyword phrase.
	 * @param string $stemmed     Optional. Stemmed form. Default empty.
	 * @param string $normalized  Optional. Accent-stripped + stemmed form. Default empty.
	 * @param int    $word_count  Optional. Word count. Default 0 (computed if zero).
	 * @param int    $row_id      Optional. Persisted row ID. Default 0.
	 * @param bool   $checked     Optional. Verified flag. Default false.
	 * @param int    $impressions Optional. GSC impressions. Default 0.
	 * @param int    $clicks      Optional. GSC clicks. Default 0.
	 */
	public function __construct(
		int $post_id,
		string $post_type,
		string $source,
		string $phrase,
		string $stemmed = '',
		string $normalized = '',
		int $word_count = 0,
		int $row_id = 0,
		bool $checked = false,
		int $impressions = 0,
		int $clicks = 0
	) {
		$this->post_id     = $post_id;
		$this->post_type   = $post_type;
		$this->source      = $source;
		$this->phrase      = $phrase;
		$this->stemmed     = $stemmed;
		$this->normalized  = $normalized;
		$this->word_count  = $word_count > 0 ? $word_count : self::count_words( $phrase );
		$this->row_id      = $row_id;
		$this->checked     = $checked;
		$this->impressions = $impressions;
		$this->clicks      = $clicks;
	}

	/**
	 * Counts whitespace-separated words in the given phrase.
	 *
	 * Trivial fallback used when the constructor receives a zero word count.
	 * The full multi-byte counter lives in WordTokenizer; we duplicate the
	 * trivial case here so the model remains free of tokeniser dependencies.
	 *
	 * @since 1.0.0
	 *
	 * @param string $phrase The phrase to count.
	 *
	 * @return int Word count.
	 */
	private static function count_words( string $phrase ): int {
		$trimmed = trim( $phrase );
		if ( '' === $trimmed ) {
			return 0;
		}
		// Split on any run of whitespace.
		$parts = preg_split( '/\s+/u', $trimmed );
		return is_array( $parts ) ? count( $parts ) : 0;
	}
}