<?php
/**
 * Removes the unused tracking_id column from the link report table.
 *
 * @package Postlinkly
 * @since   1.17.2
 */

declare(strict_types=1);

namespace Postlinkly\Bootstrap\Migrations;

use Postlinkly\Database\TableNames;

/**
 * Drops `tracking_id` from the link report table.
 *
 * The initial schema reserved the column for a click-tracking feature that
 * was never built; the setting that would have enabled it was removed in
 * 1.8.0 because nothing backed it. No code has ever written a value to it --
 * every row holds the default 0 -- and no code reads it. A column named for
 * tracking that does no tracking is still one a site owner or reviewer has
 * to investigate before trusting that nothing is collected, so it goes.
 *
 * Its index is dropped first and explicitly. MySQL would remove a
 * single-column index along with its column anyway, but saying so keeps the
 * migration's effect readable rather than dependent on that rule.
 *
 * @since 1.17.2
 */
final class Migration_006_DropUnusedTrackingColumn implements MigrationInterface {

	private const COLUMN = 'tracking_id';

	/**
	 * @since 1.17.2
	 */
	public function get_version(): int {
		return 6;
	}

	/**
	 * Drops the column when present; a site that never had it is already done.
	 *
	 * @since 1.17.2
	 *
	 * @param \wpdb $wpdb Database handle.
	 *
	 * @return bool True once the column is confirmed absent.
	 */
	public function run( \wpdb $wpdb ): bool {
		$table = $wpdb->prefix . TableNames::REPORT_LINKS;

		if ( ! $this->column_exists( $wpdb, $table ) ) {
			return true;
		}

		if ( $this->index_exists( $wpdb, $table ) ) {
			// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching,WordPress.DB.DirectDatabaseQuery.SchemaChange -- One-off schema change.
			$wpdb->query( $wpdb->prepare( 'ALTER TABLE %i DROP INDEX %i', $table, self::COLUMN ) );
		}

		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching,WordPress.DB.DirectDatabaseQuery.SchemaChange -- One-off schema change.
		$wpdb->query( $wpdb->prepare( 'ALTER TABLE %i DROP COLUMN %i', $table, self::COLUMN ) );

		// Verified rather than assumed, so a failed ALTER leaves the schema
		// version where it was and the migration retries.
		return ! $this->column_exists( $wpdb, $table );
	}

	/**
	 * Reads live schema, so its answer changes once the ALTER runs.
	 *
	 * @phpstan-impure
	 *
	 * @param \wpdb  $wpdb  Database handle.
	 * @param string $table Table name.
	 */
	private function column_exists( \wpdb $wpdb, string $table ): bool {
		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching -- Schema inspection.
		return null !== $wpdb->get_row( $wpdb->prepare( 'SHOW COLUMNS FROM %i LIKE %s', $table, self::COLUMN ) );
	}

	/**
	 * @param \wpdb  $wpdb  Database handle.
	 * @param string $table Table name.
	 */
	private function index_exists( \wpdb $wpdb, string $table ): bool {
		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching -- Schema inspection.
		return null !== $wpdb->get_row( $wpdb->prepare( 'SHOW INDEX FROM %i WHERE Key_name = %s', $table, self::COLUMN ) );
	}
}