<?php
/**
 * Manual (owner-entered) target keyword source.
 *
 * @package Postlinkly
 * @since   1.0.0
 */

declare(strict_types=1);

namespace Postlinkly\Keywords\Sources;

use Postlinkly\Database\TableNames;

/**
 * Reads target keywords that the site owner entered manually.
 *
 * These are stored directly in `postlinkly_target_keywords` with
 * `source = 'manual'`. This source is always available — it has no
 * external plugin dependency.
 *
 * @since 1.0.0
 */
final class ManualSource implements KeywordSourceInterface {

	/**
	 * Source identifier used in the database and filters.
	 */
	public const SOURCE_ID = 'manual';

	/**
	 * Returns the unique identifier for this source.
	 *
	 * @since 1.0.0
	 *
	 * @return string
	 */
	public function get_id(): string {
		return self::SOURCE_ID;
	}

	/**
	 * Returns the human-readable label for this source.
	 *
	 * @since 1.0.0
	 *
	 * @return string
	 */
	public function get_label(): string {
		return __( 'Manual', 'postlinkly' );
	}

	/**
	 * Whether this keyword source is available on the current site.
	 *
	 * Always available — no external plugin required.
	 *
	 * @since 1.0.0
	 *
	 * @return bool
	 */
	public function is_available(): bool {
		return true;
	}

	/**
	 * Returns manually-entered keyword phrases for a post or term.
	 *
	 * @since 1.0.0
	 *
	 * @param int    $post_id   Post or term identifier.
	 * @param string $post_type Item type. Default `post`.
	 *
	 * @return array<int, string> Raw phrases.
	 */
	public function get_keywords_for( int $post_id, string $post_type = 'post' ): array {
		global $wpdb;

		if ( ! isset( $wpdb ) || $post_id <= 0 ) {
			return array();
		}

		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching -- Caching is the manager's responsibility; this source is intentionally thin.
		$rows = $wpdb->get_results(
			$wpdb->prepare(
				'SELECT phrase FROM %i WHERE post_id = %d AND post_type = %s AND source = %s',
				TableNames::target_keywords(),
				$post_id,
				$post_type,
				self::SOURCE_ID
			)
		);

		if ( ! is_array( $rows ) ) {
			return array();
		}

		$out = array();
		foreach ( $rows as $row ) {
			if ( ! is_object( $row ) || ! isset( $row->phrase ) ) {
				continue;
			}
			$phrase = trim( (string) $row->phrase );
			if ( '' !== $phrase ) {
				$out[] = $phrase;
			}
		}
		return $out;
	}
}