<?php
/**
 * Reusable database query helpers.
 *
 * @package Postlinkly
 * @since   1.0.0
 */

declare(strict_types=1);

namespace Postlinkly\Database;

/**
 * Reusable database query helpers.
 *
 * Small static utilities for common patterns: building IN clauses,
 * standard post-status lists, integer ID coercion. Keeping these here
 * means the rest of the codebase doesn't reinvent them.
 *
 * Helpers that need `$wpdb` accept it as a parameter rather than reaching
 * for the global, so callers can mock it in tests.
 *
 * @since 1.0.0
 */
final class Query {

	/**
	 * Builds a parenthesised IN clause from a list of integer IDs.
	 *
	 * Returns an empty string for empty input — callers must special-case
	 * empty input (typically by returning an empty result without running
	 * the query). This is safer than producing `IN ()`, which is invalid
	 * SQL, or `IN (NULL)`, which silently matches nothing.
	 *
	 * @since 1.0.0
	 *
	 * @param array<int, int|string> $ids List of identifiers.
	 *
	 * @return string Parenthesised list of integers, or empty string.
	 */
	public static function in_clause_int( array $ids ): string {
		$cleaned = array();
		foreach ( $ids as $id ) {
			$id = (int) $id;
			if ( $id > 0 ) {
				$cleaned[] = $id;
			}
		}
		if ( array() === $cleaned ) {
			return '';
		}
		return '(' . implode( ',', $cleaned ) . ')';
	}

	/**
	 * Builds a parenthesised IN clause from a list of strings, escaped via $wpdb->prepare.
	 *
	 * @since 1.0.0
	 *
	 * @param \wpdb               $wpdb   WordPress database instance.
	 * @param array<int, string>  $values Values to escape and join.
	 *
	 * @return string Parenthesised list of quoted strings, or empty string.
	 */
	public static function in_clause_string( \wpdb $wpdb, array $values ): string {
		$cleaned = array();
		foreach ( $values as $value ) {
			$value = (string) $value;
			if ( '' !== $value ) {
				$cleaned[] = $value;
			}
		}
		if ( array() === $cleaned ) {
			return '';
		}
		$placeholders = implode( ',', array_fill( 0, count( $cleaned ), '%s' ) );
		// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- Placeholders constructed locally; values pass through prepare().
		$prepared = $wpdb->prepare( $placeholders, $cleaned );
		return '(' . $prepared . ')';
	}

	/**
	 * Returns the standard list of "public-ish" post statuses to scan.
	 *
	 * Excludes `trash`, `auto-draft`, and `inherit`. Reasonable default for
	 * link reports — most callers want to see anything that's published or
	 * actively being worked on, but not posts in the trash.
	 *
	 * @since 1.0.0
	 *
	 * @return array<int, string> Status slugs.
	 */
	public static function default_post_statuses(): array {
		return array( 'publish', 'pending', 'draft', 'future', 'private' );
	}

	/**
	 * Coerces a list of mixed-type IDs to a clean list of positive integers.
	 *
	 * Drops zero, negative, and non-numeric entries. Preserves order and
	 * does not deduplicate (callers who want unique IDs can `array_unique`
	 * the result).
	 *
	 * @since 1.0.0
	 *
	 * @param array<int, int|string> $ids Raw ID list.
	 *
	 * @return array<int, int> Sanitised list of positive integers.
	 */
	public static function sanitise_int_ids( array $ids ): array {
		$out = array();
		foreach ( $ids as $id ) {
			$id = (int) $id;
			if ( $id > 0 ) {
				$out[] = $id;
			}
		}
		return $out;
	}
}