<?php
/**
 * Suggestion settings DTO.
 *
 * @package Postlinkly
 * @since   1.0.0
 */

declare(strict_types=1);

namespace Postlinkly\Settings;

/**
 * Suggestion settings DTO.
 *
 * Controls how the suggestion engine behaves — what it suggests,
 * how many, and what quality constraints to apply.
 *
 * @since 1.0.0
 */
final class SuggestionSettings {

	/**
	 * Maximum number of suggestions to return per post.
	 *
	 * @var int
	 */
	public int $max_suggestions;

	/**
	 * Minimum anchor length in words.
	 *
	 * @var int
	 */
	public int $min_anchor_words;

	/**
	 * Maximum anchor length in words.
	 *
	 * @var int
	 */
	public int $max_anchor_words;

	/**
	 * Maximum number of outbound links to insert per post.
	 *
	 * 0 means no limit.
	 *
	 * @var int
	 */
	public int $max_links_per_post;

	/**
	 * Maximum number of inbound links a post can receive.
	 *
	 * 0 means no limit. Prevents one popular post from being linked
	 * to from every other post on the site.
	 *
	 * @var int
	 */
	public int $max_inbound_links_per_post;

	/**
	 * Only suggest links to posts published within this many months.
	 *
	 * 0 means no age limit — suggest links to any published post.
	 *
	 * @var int
	 */
	public int $max_post_age_months;

	/**
	 * Whether to skip the first N paragraphs when scanning for anchors.
	 *
	 * @var int
	 */
	public int $skip_paragraphs;

	/**
	 * Whether to prevent two-way linking.
	 *
	 * When true, if post A already links to post B, the engine will not
	 * suggest linking post B back to post A.
	 *
	 * @var bool
	 */
	public bool $prevent_two_way_linking;

	/**
	 * Whether to prevent keyword cannibalization.
	 *
	 * When true, if a post already has an outbound link using a given
	 * anchor phrase, the engine will not suggest the same anchor for
	 * a different target.
	 *
	 * @var bool
	 */
	public bool $prevent_cannibalization;

	/**
	 * Phrases that should never be used as anchor text.
	 *
	 * Comma-separated list stored as a single string; split on load.
	 *
	 * @var array<int, string>
	 */
	public array $ignore_phrases;

	/**
	 * @since 1.0.0
	 * @since 1.8.0 Default for $prevent_cannibalization changed to true.
	 *        Default changed to true so gating this behind the setting
	 *        doesn't silently change existing suggestion output.
	 *
	 * @param int                $max_suggestions            Optional. Default 10.
	 * @param int                $min_anchor_words           Optional. Default 1.
	 * @param int                $max_anchor_words           Optional. Default 6.
	 * @param int                $max_links_per_post         Optional. Default 0 (no limit).
	 * @param int                $max_inbound_links_per_post Optional. Default 0 (no limit).
	 * @param int                $max_post_age_months        Optional. Default 0 (no limit).
	 * @param int                $skip_paragraphs            Optional. Default 0.
	 * @param bool               $prevent_two_way_linking    Optional. Default false.
	 * @param bool               $prevent_cannibalization    Optional. Default true.
	 * @param array<int, string> $ignore_phrases             Optional. Default [].
	 */
	public function __construct(
		int $max_suggestions = 10,
		int $min_anchor_words = 1,
		int $max_anchor_words = 6,
		int $max_links_per_post = 0,
		int $max_inbound_links_per_post = 0,
		int $max_post_age_months = 0,
		int $skip_paragraphs = 0,
		bool $prevent_two_way_linking = false,
		bool $prevent_cannibalization = true,
		array $ignore_phrases = array()
	) {
		$this->max_suggestions            = max( 1, $max_suggestions );
		$this->min_anchor_words           = max( 1, $min_anchor_words );
		$this->max_anchor_words           = max( $this->min_anchor_words, $max_anchor_words );
		$this->max_links_per_post         = max( 0, $max_links_per_post );
		$this->max_inbound_links_per_post = max( 0, $max_inbound_links_per_post );
		$this->max_post_age_months        = max( 0, $max_post_age_months );
		$this->skip_paragraphs            = max( 0, $skip_paragraphs );
		$this->prevent_two_way_linking    = $prevent_two_way_linking;
		$this->prevent_cannibalization    = $prevent_cannibalization;
		$this->ignore_phrases             = array_values(
			array_filter( $ignore_phrases, static fn( $p ) => is_string( $p ) && '' !== trim( $p ) )
		);
	}

	/**
	 * Creates an instance from a raw settings array.
	 *
	 * @since 1.0.0
	 *
	 * @param array<string, mixed> $data Raw settings data.
	 *
	 * @return self
	 */
	public static function from_array( array $data ): self {
		// ignore_phrases may arrive as a comma-separated string from the form.
		$raw_phrases = $data['ignore_phrases'] ?? array();
		if ( is_string( $raw_phrases ) ) {
			$raw_phrases = array_map( 'trim', explode( ',', $raw_phrases ) );
		}
		$ignore_phrases = is_array( $raw_phrases )
			? array_values( array_filter( $raw_phrases, static fn( $p ) => is_string( $p ) && '' !== trim( $p ) ) )
			: array();

		return new self(
			(int) ( $data['max_suggestions'] ?? 10 ),
			(int) ( $data['min_anchor_words'] ?? 1 ),
			(int) ( $data['max_anchor_words'] ?? 6 ),
			(int) ( $data['max_links_per_post'] ?? 0 ),
			(int) ( $data['max_inbound_links_per_post'] ?? 0 ),
			(int) ( $data['max_post_age_months'] ?? 0 ),
			(int) ( $data['skip_paragraphs'] ?? 0 ),
			(bool) ( $data['prevent_two_way_linking'] ?? false ),
			(bool) ( $data['prevent_cannibalization'] ?? true ),
			$ignore_phrases
		);
	}

	/**
	 * Serializes settings to an array for storage.
	 *
	 * @since 1.0.0
	 *
	 * @return array<string, mixed>
	 */
	public function to_array(): array {
		return array(
			'max_suggestions'            => $this->max_suggestions,
			'min_anchor_words'           => $this->min_anchor_words,
			'max_anchor_words'           => $this->max_anchor_words,
			'max_links_per_post'         => $this->max_links_per_post,
			'max_inbound_links_per_post' => $this->max_inbound_links_per_post,
			'max_post_age_months'        => $this->max_post_age_months,
			'skip_paragraphs'            => $this->skip_paragraphs,
			'prevent_two_way_linking'    => $this->prevent_two_way_linking,
			'prevent_cannibalization'    => $this->prevent_cannibalization,
			'ignore_phrases'             => $this->ignore_phrases,
		);
	}
}