<?php
/**
 * TMDO_Commentmeta_Cleaner — wp_commentmeta garbage cleanup (v2.12.0 Phase 0).
 *
 * Identifies and removes four classes of low-value rows from wp_commentmeta
 * that bloat the table without serving any business purpose:
 *
 *   - wxr_import       — `_wxr_import_*` rows from WP importer (pure tracking)
 *                        On dev10 alone: 211 rows = 75% of all commentmeta
 *   - demo_data        — `_2meet_demo_*` rows used to mark demo content
 *   - transients       — `_transient_*` and `_transient_timeout_*` rows
 *   - orphan_post_meta — Stray post-meta keys mistakenly written to
 *                        commentmeta (e.g., `_hp_price`, `_hp_status`,
 *                        `_thumbnail_id`). These are bugs / typos / earlier
 *                        plugin defects — never read from commentmeta.
 *
 * Mirrors TMDO_Postmeta_Cleaner / TMDO_Termmeta_Cleaner pattern.
 *
 * @package WP_Data_Optimizer
 * @since   2.12.0
 */

declare(strict_types=1);

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Wp_commentmeta garbage cleanup (v2.12.0 Phase 0).
 */
class TMDO_Commentmeta_Cleaner {

	public const TARGET_WXR_IMPORT       = 'wxr_import';
	public const TARGET_DEMO_DATA        = 'demo_data';
	public const TARGET_TRANSIENTS       = 'transients';
	public const TARGET_ORPHAN_POST_META = 'orphan_post_meta';
	public const TARGET_ALL              = 'all';

	public const VALID_TARGETS = array(
		self::TARGET_WXR_IMPORT,
		self::TARGET_DEMO_DATA,
		self::TARGET_TRANSIENTS,
		self::TARGET_ORPHAN_POST_META,
		self::TARGET_ALL,
	);

	/**
	 * Known post-meta keys that have been observed mis-written to commentmeta.
	 * Conservative list — only includes keys that:
	 *   1. Are clearly post-domain (start with `_hp_*` / `_thumbnail_id` / etc.)
	 *   2. Have NO known consumer reading from get_comment_meta() with that key
	 *   3. Were observed in real production data (dev10) as orphan rows
	 */
	private const ORPHAN_POST_META_KEYS = array(
		'_hp_price',
		'_hp_status',
		'_hp_featured',
		'_hp_verified',
		'_hp_view_count',
		'_thumbnail_id',
		'_edit_lock',
		'_edit_last',
	);

	/**
	 * Count rows that would be cleaned for the given target.
	 *
	 * @param string $target One of TARGET_* constants.
	 * @return array{wxr_import:int, demo_data:int, transients:int, orphan_post_meta:int, total:int}
	 * @throws InvalidArgumentException When $target is not a valid target.
	 */
	public static function count_garbage( string $target = self::TARGET_ALL ): array {
		self::assert_valid_target( $target );

		$counts = array(
			'wxr_import'       => 0,
			'demo_data'        => 0,
			'transients'       => 0,
			'orphan_post_meta' => 0,
			'total'            => 0,
		);

		if ( self::target_includes( $target, self::TARGET_WXR_IMPORT ) ) {
			$counts['wxr_import'] = self::count_wxr_import();
		}
		if ( self::target_includes( $target, self::TARGET_DEMO_DATA ) ) {
			$counts['demo_data'] = self::count_demo_data();
		}
		if ( self::target_includes( $target, self::TARGET_TRANSIENTS ) ) {
			$counts['transients'] = self::count_transients();
		}
		if ( self::target_includes( $target, self::TARGET_ORPHAN_POST_META ) ) {
			$counts['orphan_post_meta'] = self::count_orphan_post_meta();
		}

		$counts['total'] = $counts['wxr_import'] + $counts['demo_data']
			+ $counts['transients'] + $counts['orphan_post_meta'];
		return $counts;
	}

	/**
	 * Delete garbage rows for the given target.
	 *
	 * @param string $target One of TARGET_* constants.
	 * @return array{wxr_import:int, demo_data:int, transients:int, orphan_post_meta:int, total:int}
	 * @throws InvalidArgumentException When $target is not a valid target.
	 */
	public static function delete_garbage( string $target = self::TARGET_ALL ): array {
		self::assert_valid_target( $target );

		$deleted = array(
			'wxr_import'       => 0,
			'demo_data'        => 0,
			'transients'       => 0,
			'orphan_post_meta' => 0,
			'total'            => 0,
		);

		if ( self::target_includes( $target, self::TARGET_WXR_IMPORT ) ) {
			$deleted['wxr_import'] = self::delete_wxr_import();
		}
		if ( self::target_includes( $target, self::TARGET_DEMO_DATA ) ) {
			$deleted['demo_data'] = self::delete_demo_data();
		}
		if ( self::target_includes( $target, self::TARGET_TRANSIENTS ) ) {
			$deleted['transients'] = self::delete_transients();
		}
		if ( self::target_includes( $target, self::TARGET_ORPHAN_POST_META ) ) {
			$deleted['orphan_post_meta'] = self::delete_orphan_post_meta();
		}

		$deleted['total'] = $deleted['wxr_import'] + $deleted['demo_data']
			+ $deleted['transients'] + $deleted['orphan_post_meta'];
		return $deleted;
	}

	/**
	 * Whether $target selects $bucket (i.e. target=all or target=bucket).
	 *
	 * @param string $target Selected target.
	 * @param string $bucket Bucket constant.
	 * @return bool
	 */
	private static function target_includes( string $target, string $bucket ): bool {
		return self::TARGET_ALL === $target || $bucket === $target;
	}

	/**
	 * Validate target parameter.
	 *
	 * @param string $target Target to validate.
	 * @return void
	 * @throws InvalidArgumentException When $target is not in VALID_TARGETS.
	 */
	private static function assert_valid_target( string $target ): void {
		if ( in_array( $target, self::VALID_TARGETS, true ) ) {
			return;
		}
		$msg = sprintf( 'Invalid target "%s". Valid: %s', $target, implode( ', ', self::VALID_TARGETS ) );
		throw new InvalidArgumentException( $msg ); // phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped
	}

	// phpcs:disable WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching,WordPress.DB.PreparedSQL.InterpolatedNotPrepared -- Internal cleanup class: $wpdb->commentmeta is WP-managed; meta_key patterns are static class constants.

	/**
	 * Count `_wxr_import_*` rows in wp_commentmeta.
	 *
	 * @return int
	 */
	private static function count_wxr_import(): int {
		global $wpdb;
		$table = $wpdb->commentmeta;
		return (int) $wpdb->get_var(
			"SELECT COUNT(*) FROM `{$table}` WHERE meta_key LIKE '\\_wxr\\_import\\_%'"
		);
	}

	/**
	 * Delete `_wxr_import_*` rows from wp_commentmeta.
	 *
	 * @return int Affected row count.
	 */
	private static function delete_wxr_import(): int {
		global $wpdb;
		$table = $wpdb->commentmeta;
		return (int) $wpdb->query(
			"DELETE FROM `{$table}` WHERE meta_key LIKE '\\_wxr\\_import\\_%'"
		);
	}

	/**
	 * Count `_2meet_demo_*` rows in wp_commentmeta.
	 *
	 * @return int
	 */
	private static function count_demo_data(): int {
		global $wpdb;
		$table = $wpdb->commentmeta;
		return (int) $wpdb->get_var(
			"SELECT COUNT(*) FROM `{$table}` WHERE meta_key LIKE '\\_2meet\\_demo\\_%'"
		);
	}

	/**
	 * Delete `_2meet_demo_*` rows from wp_commentmeta.
	 *
	 * @return int Affected row count.
	 */
	private static function delete_demo_data(): int {
		global $wpdb;
		$table = $wpdb->commentmeta;
		return (int) $wpdb->query(
			"DELETE FROM `{$table}` WHERE meta_key LIKE '\\_2meet\\_demo\\_%'"
		);
	}

	/**
	 * Count rows matching transient meta_key patterns in wp_commentmeta.
	 *
	 * @return int
	 */
	private static function count_transients(): int {
		global $wpdb;
		$table = $wpdb->commentmeta;
		return (int) $wpdb->get_var(
			"SELECT COUNT(*) FROM `{$table}` WHERE meta_key LIKE '\\_transient\\_%' OR meta_key LIKE '\\_transient\\_timeout\\_%'"
		);
	}

	/**
	 * Delete rows matching transient meta_key patterns from wp_commentmeta.
	 *
	 * @return int Affected row count.
	 */
	private static function delete_transients(): int {
		global $wpdb;
		$table = $wpdb->commentmeta;
		return (int) $wpdb->query(
			"DELETE FROM `{$table}` WHERE meta_key LIKE '\\_transient\\_%' OR meta_key LIKE '\\_transient\\_timeout\\_%'"
		);
	}

	/**
	 * Count orphan post-meta keys in wp_commentmeta.
	 *
	 * @return int
	 */
	private static function count_orphan_post_meta(): int {
		global $wpdb;
		$table        = $wpdb->commentmeta;
		$placeholders = implode( ',', array_fill( 0, count( self::ORPHAN_POST_META_KEYS ), '%s' ) );
		return (int) $wpdb->get_var(
			$wpdb->prepare(
				"SELECT COUNT(*) FROM `{$table}` WHERE meta_key IN ({$placeholders})",
				...self::ORPHAN_POST_META_KEYS
			)
		);
	}

	/**
	 * Delete orphan post-meta keys from wp_commentmeta.
	 *
	 * @return int Affected row count.
	 */
	private static function delete_orphan_post_meta(): int {
		global $wpdb;
		$table        = $wpdb->commentmeta;
		$placeholders = implode( ',', array_fill( 0, count( self::ORPHAN_POST_META_KEYS ), '%s' ) );
		return (int) $wpdb->query(
			$wpdb->prepare(
				"DELETE FROM `{$table}` WHERE meta_key IN ({$placeholders})",
				...self::ORPHAN_POST_META_KEYS
			)
		);
	}

	// phpcs:enable WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching,WordPress.DB.PreparedSQL.InterpolatedNotPrepared
}