2meet-data-optimizer/includes/migration/class-tmdo-native-restorer.php

<?php
/**
 * TMDO_Native_Restorer — write flat-table values back to native meta.
 *
 * The only way out of aeav_only: in that mode the flat tables are the sole
 * copy of every managed key, and demoting the entity (or uninstalling) would
 * leave reads on native meta that no longer has the data.
 *
 * Rule: afterwards native meta returns what reads return today.
 *   - A key is written from the group that currently owns it for that entity
 *     (TMDO_Entity_Registry::get_field(), by post type for posts), so stale
 *     copies in other group tables never win.
 *   - Non-NULL values are stored the way WP stores them (maybe_serialize of
 *     the value Type_Caster returns); a NULL value deletes the native row.
 *   - Entities with no row in the owning group's table are not touched:
 *     leftover native rows for them are outside the flat data.
 *
 * Batched by entity id with a cursor option so an interrupted run resumes; a
 * final pass re-copies rows updated since the first run started. With
 * $demote the entity then moves to dual_write, which keeps both copies in
 * step from then on.
 *
 * A single group can be written back on its own ($group) and then retired:
 * retire() forgets its registry_meta row and keeps the flat table under a
 * `_retired_<Ymd>` name, so orphan restore never routes its keys again.
 *
 * @package WP_Data_Optimizer
 */

declare(strict_types=1);

defined( 'ABSPATH' ) || exit;

// phpcs:disable WordPress.DB.PreparedSQL.InterpolatedNotPrepared,WordPress.DB.PreparedSQL.NotPrepared,WordPress.DB.DirectDatabaseQuery,WordPress.DB.PreparedSQLPlaceholders.ReplacementsWrongNumber,WordPress.DB.PreparedSQLPlaceholders.UnfinishedPrepare -- table/column names come from the entity registry / adapter; placeholders are built for spread params.

/**
 * Copies flat-table values of one entity type back into its native meta table.
 */
final class TMDO_Native_Restorer {

	/** Option: "entity/group" → last entity id written. */
	public const CURSOR_OPTION = 'tmdo_restore_native_cursor';

	/** Option: entity → DB time its first (possibly interrupted) run started. */
	public const STARTED_OPTION = 'tmdo_restore_native_started';

	/**
	 * Restore one entity type (or, with $dry_run, count the rows involved).
	 *
	 * @param string $entity_type 'post' | 'user' | 'term' | 'comment'.
	 * @param bool   $dry_run     Count only; write nothing.
	 * @param int    $batch       Rows per batch.
	 * @param bool   $demote      After a complete run, switch the entity to dual_write.
	 * @param string $group       Only this group ('' = every group).
	 * @return array{groups: array<string, array{rows:int, written:int}>, demoted: bool}
	 */
	public static function run( string $entity_type, bool $dry_run = false, int $batch = 500, bool $demote = false, string $group = '' ): array {
		global $wpdb;

		$report  = array(
			'groups'  => array(),
			'demoted' => false,
		);
		$adapter = TMDO_Entity_Registry::get_adapter( $entity_type );
		if ( ! $adapter ) {
			return $report;
		}
		$id_col = $adapter->get_entity_id_column();
		$batch  = max( 1, $batch );

		$started = get_option( self::STARTED_OPTION, array() );
		$started = is_array( $started ) ? $started : array();
		if ( ! $dry_run && ! isset( $started[ $entity_type ] ) ) {
			$started[ $entity_type ] = (string) $wpdb->get_var( 'SELECT NOW()' );
			update_option( self::STARTED_OPTION, $started, false );
		}
		$cursor = get_option( self::CURSOR_OPTION, array() );
		$cursor = is_array( $cursor ) ? $cursor : array();

		$tables = self::group_tables( $entity_type );
		if ( '' !== $group ) {
			$tables = array_intersect_key( $tables, array( $group => true ) );
		}
		foreach ( $tables as $group => $table ) {
			$entry = array(
				'rows'    => 0,
				'written' => 0,
			);
			$key   = "{$entity_type}/{$group}";
			$last  = $dry_run ? 0 : (int) ( $cursor[ $key ] ?? 0 );
			do {
				$rows           = self::fetch( $entity_type, $table, $id_col, "t.`{$id_col}` > %d ORDER BY t.`{$id_col}` LIMIT %d", array( $last, $batch ) );
				$fetched        = count( $rows );
				$entry['rows'] += $fetched;
				if ( $fetched ) {
					$last = (int) end( $rows )[ $id_col ];
					if ( ! $dry_run ) {
						$entry['written'] += self::write_rows( $entity_type, $group, $adapter, $rows );
						$cursor[ $key ]    = $last;
						update_option( self::CURSOR_OPTION, $cursor, false );
					}
				}
			} while ( $fetched === $batch );

			$report['groups'][ $group ] = $entry;
		}

		if ( $dry_run ) {
			return $report;
		}

		// Catch-up: writes that landed in the flat tables after a batch passed their row.
		foreach ( $tables as $group => $table ) {
			$rows = self::fetch( $entity_type, $table, $id_col, 't.updated_at >= %s', array( $started[ $entity_type ] ) );
			self::write_rows( $entity_type, $group, $adapter, $rows );
		}

		foreach ( array_keys( $tables ) as $group ) {
			unset( $cursor[ "{$entity_type}/{$group}" ] );
		}
		unset( $started[ $entity_type ] );
		$cursor ? update_option( self::CURSOR_OPTION, $cursor, false ) : delete_option( self::CURSOR_OPTION );
		$started ? update_option( self::STARTED_OPTION, $started, false ) : delete_option( self::STARTED_OPTION );

		if ( $demote ) {
			$report['demoted'] = true === TMDO_Mode_Manager::set( $entity_type, TMDO_Mode_Manager::MODE_DUAL_WRITE );
		}

		return $report;
	}

	/**
	 * Forget a group that no plugin registers any more, once native meta holds
	 * every non-NULL value of its flat table (run() with $group first).
	 *
	 * @param string $entity_type Entity type.
	 * @param string $group       Group name.
	 * @return array{status:string, mismatches:int, archived_table:string}
	 *   status: retired | registered (a plugin still registers it) |
	 *   missing (no registry_meta row or flat table) | mismatch (native differs).
	 */
	public static function retire( string $entity_type, string $group ): array {
		global $wpdb;
		$result   = array(
			'status'         => 'missing',
			'mismatches'     => 0,
			'archived_table' => '',
		);
		$restored = array_map( static fn( $r ) => $r['entity_type'] . '/' . $r['group'], TMDO_Entity_Registry::get_restored_groups() );
		if ( TMDO_Entity_Registry::get_group_fields( $entity_type, $group ) && ! in_array( "{$entity_type}/{$group}", $restored, true ) ) {
			$result['status'] = 'registered';
			return $result;
		}
		$adapter    = TMDO_Entity_Registry::get_adapter( $entity_type );
		$meta_table = $wpdb->prefix . TMDO_TABLE_PREFIX . 'registry_meta';
		$table      = TMDO_Schema_Manager::get_table_name( $entity_type, $group );
		$defs       = $wpdb->get_var( $wpdb->prepare( "SELECT field_definitions FROM `{$meta_table}` WHERE entity_type = %s AND group_name = %s", $entity_type, $group ) );
		$fields     = json_decode( (string) $defs, true );
		if ( ! $adapter || ! is_array( $fields ) || null === $wpdb->get_var( $wpdb->prepare( 'SHOW TABLES LIKE %s', $table ) ) ) {
			return $result;
		}

		$native_table = $adapter->get_native_meta_table();
		$id_col       = $adapter->get_entity_id_column();
		foreach ( (array) $wpdb->get_results( "SELECT * FROM `{$table}`", ARRAY_A ) as $row ) {
			foreach ( $fields as $field ) {
				$col = TMDO_Schema_Manager::sanitize_column_name( (string) ( $field['key'] ?? '' ) );
				if ( '' === $col || ! isset( $row[ $col ] ) ) {
					continue;
				}
				$want = (string) maybe_serialize( TMDO_Type_Caster::from_db( $row[ $col ], $field ) );
				// get_results(), not get_col(): wpdb reads an empty string as null.
				$native = array_column( (array) $wpdb->get_results( $wpdb->prepare( "SELECT meta_value FROM `{$native_table}` WHERE `{$id_col}` = %d AND meta_key = %s", (int) $row[ $id_col ], $field['key'] ), ARRAY_A ), 'meta_value' );
				if ( array( $want ) !== $native ) {
					++$result['mismatches'];
				}
			}
		}
		if ( $result['mismatches'] ) {
			$result['status'] = 'mismatch';
			return $result;
		}

		$archived = $table . '_retired_' . gmdate( 'Ymd' );
		$wpdb->query( "RENAME TABLE `{$table}` TO `{$archived}`" );
		$wpdb->delete(
			$meta_table,
			array(
				'entity_type' => $entity_type,
				'group_name'  => $group,
			)
		);
		delete_transient( 'tmdo_orphan_native_keys' );
		TMDO_Schema_Manager::flush_table_exists_cache();

		$result['status']         = 'retired';
		$result['archived_table'] = $archived;
		return $result;
	}

	/**
	 * Registered groups of the entity whose flat table exists.
	 *
	 * @param string $entity_type Entity type.
	 * @return array<string, string> Group → table name.
	 */
	private static function group_tables( string $entity_type ): array {
		$tables = array();
		foreach ( TMDO_Entity_Registry::get_groups_for_type( $entity_type ) as $group ) {
			$table = TMDO_Schema_Manager::get_table_name( $entity_type, $group );
			if ( TMDO_Schema_Manager::table_exists( $table ) ) {
				$tables[ $group ] = $table;
			}
		}
		return $tables;
	}

	/**
	 * Flat rows matching $where; post rows carry their post type as __post_type.
	 *
	 * @param string $entity_type Entity type.
	 * @param string $table       Flat table.
	 * @param string $id_col      Entity id column.
	 * @param string $where       WHERE clause with placeholders.
	 * @param array  $params      Placeholder values.
	 * @return array<int, array<string, mixed>>
	 */
	private static function fetch( string $entity_type, string $table, string $id_col, string $where, array $params ): array {
		global $wpdb;
		$select = 'post' === $entity_type
			? "SELECT t.*, p.post_type AS __post_type FROM `{$table}` t LEFT JOIN `{$wpdb->posts}` p ON p.ID = t.`{$id_col}`"
			: "SELECT t.* FROM `{$table}` t";

		return (array) $wpdb->get_results( $wpdb->prepare( "{$select} WHERE {$where}", ...$params ), ARRAY_A );
	}

	/**
	 * Replace the native meta of the keys this group owns for each row.
	 *
	 * @param string                        $entity_type Entity type.
	 * @param string                        $group       Group the rows come from.
	 * @param TMDO_Entity_Adapter_Interface $adapter     Entity adapter.
	 * @param array                         $rows        Flat rows.
	 * @return int Native values written.
	 */
	private static function write_rows( string $entity_type, string $group, TMDO_Entity_Adapter_Interface $adapter, array $rows ): int {
		global $wpdb;
		if ( empty( $rows ) ) {
			return 0;
		}
		$meta_table = $adapter->get_native_meta_table();
		$id_col     = $adapter->get_entity_id_column();

		$deletes = array();
		$inserts = array();
		foreach ( $rows as $row ) {
			$id        = (int) $row[ $id_col ];
			$post_type = 'post' === $entity_type ? (string) ( $row['__post_type'] ?? '' ) : '';
			foreach ( TMDO_Entity_Registry::get_group_fields( $entity_type, $group ) as $field ) {
				$owner = TMDO_Entity_Registry::get_field( $entity_type, $field['key'], $post_type );
				$col   = TMDO_Schema_Manager::sanitize_column_name( $field['key'] );
				if ( null === $owner || $owner['group'] !== $group || ! array_key_exists( $col, $row ) ) {
					continue;
				}
				$deletes[ $field['key'] ][] = $id;
				if ( null !== $row[ $col ] ) {
					$inserts[] = array( $id, $field['key'], (string) maybe_serialize( TMDO_Type_Caster::from_db( $row[ $col ], $field ) ) );
				}
			}
		}

		foreach ( $deletes as $meta_key => $ids ) {
			$in = implode( ',', array_map( 'intval', $ids ) );
			$wpdb->query( $wpdb->prepare( "DELETE FROM `{$meta_table}` WHERE meta_key = %s AND `{$id_col}` IN ({$in})", $meta_key ) );
		}
		if ( $inserts ) {
			$values = implode( ', ', array_fill( 0, count( $inserts ), '(%d, %s, %s)' ) );
			$wpdb->query( $wpdb->prepare( "INSERT INTO `{$meta_table}` (`{$id_col}`, meta_key, meta_value) VALUES {$values}", ...array_merge( ...$inserts ) ) );
		}

		foreach ( array_unique( array_map( static fn( $row ) => (int) $row[ $id_col ], $rows ) ) as $id ) {
			wp_cache_delete( $id, "{$entity_type}_meta" );
		}
		return count( $inserts );
	}
}