<?php
/**
 * Read and write helpers for WordPress taxonomy terms.
 *
 * @package Postlinkly
 * @since   1.0.0
 */

declare(strict_types=1);

namespace Postlinkly\Post;

/**
 * Read and write helpers for WordPress taxonomy terms.
 *
 * Mirrors {@see PostRepository} for terms. Returns the same `PostModel`
 * value object so callers downstream (suggestion engine, list tables) can
 * treat posts and terms uniformly.
 *
 * Link-count meta is stored as term meta (introduced in WP 4.4) using
 * keys identical to the post equivalents — the namespace separator
 * (`post:` vs. `term:`) lives on the model, not on the meta key.
 *
 * @since 1.0.0
 */
final class TermRepository {

	/**
	 * Returns a PostModel for the given term ID, or null when not found.
	 *
	 * Returns null on any WP_Error — terms that don't exist or can't be
	 * loaded due to taxonomy mismatch should not crash the caller.
	 *
	 * @since 1.0.0
	 *
	 * @param int $id Term identifier.
	 *
	 * @return PostModel|null Hydrated model, or null when no term exists for $id.
	 */
	public function find( int $id ): ?PostModel {
		if ( $id <= 0 ) {
			return null;
		}
		$term = get_term( $id );
		if ( null === $term || is_wp_error( $term ) ) {
			return null;
		}

		return new PostModel(
			(int) $term->term_id,
			PostModel::TYPE_TERM,
			(string) $term->name,
			'publish',
			(string) $term->slug
		);
	}

	/**
	 * Returns PostModels for a list of term IDs, in input order.
	 *
	 * Skips IDs that don't resolve to a term. Returns an empty array for
	 * an empty input.
	 *
	 * @since 1.0.0
	 *
	 * @param array<int, int|string> $ids Term identifiers.
	 *
	 * @return array<int, PostModel>
	 */
	public function find_many( array $ids ): array {
		$out = array();
		foreach ( $ids as $id ) {
			$model = $this->find( (int) $id );
			if ( null !== $model ) {
				$out[] = $model;
			}
		}
		return $out;
	}

	/**
	 * Returns the stored link counts for a term.
	 *
	 * @since 1.0.0
	 *
	 * @param int $term_id Term identifier.
	 *
	 * @return array{inbound: int, outbound: int, external: int}
	 */
	public function get_link_counts( int $term_id ): array {
		return array(
			'inbound'  => (int) get_term_meta( $term_id, PostRepository::META_INBOUND_INTERNAL, true ),
			'outbound' => (int) get_term_meta( $term_id, PostRepository::META_OUTBOUND_INTERNAL, true ),
			'external' => (int) get_term_meta( $term_id, PostRepository::META_OUTBOUND_EXTERNAL, true ),
		);
	}

	/**
	 * Writes the link counts for a term.
	 *
	 * @since 1.0.0
	 *
	 * @param int $term_id  Term identifier.
	 * @param int $inbound  Inbound internal link count.
	 * @param int $outbound Outbound internal link count.
	 * @param int $external Outbound external link count.
	 *
	 * @return void
	 */
	public function update_link_counts( int $term_id, int $inbound, int $outbound, int $external ): void {
		update_term_meta( $term_id, PostRepository::META_INBOUND_INTERNAL, max( 0, $inbound ) );
		update_term_meta( $term_id, PostRepository::META_OUTBOUND_INTERNAL, max( 0, $outbound ) );
		update_term_meta( $term_id, PostRepository::META_OUTBOUND_EXTERNAL, max( 0, $external ) );
	}
}