wpdev/2meet-data-optimizer
1
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases 1 Wiki Activity

refactor(migration): 回填 Migration Phase Strategy 體系（PR-D）

Browse Source 
A v3.0.1 把 orchestrator 的 11 個 phase 抽成可注入的 Phase 物件，B 仍是
1107 行單體、以 'phase_' . $current 字串魔法分派、completed 甚至 inline
在 tick() 裡。本 commit 對齊：

新增 13 檔
- includes/migration/interface-migration-phase.php
- includes/migration/class-tmdo-migration-phase-base.php（log/get_managed_keys/
  execute_bulk_pivot/values_loose_equal 等共用 helper）
- includes/migration/phases/ 11 個 phase 類別

orchestrator 1107 → 640 行
- tick() 改 make_phase() 工廠 + $phase->execute($job)
- 移除 final、self::ENTITY_TYPE → static::（A v3.3.0 late static binding）
- 保留 B 原有的 '✓ %s (%.2fs)' 耗時 log（改為 tick 自行量測，A 版已簡化掉）
- 公開介面（preflight/start/tick/get_status/cancel/resume/needs_attention/
  cron_tick）經 diff 確認與 A 完全一致，呼叫端零影響

連帶
- Schema_Manager 補 table_exists 的 request-scoped cache 與
  flush_table_exists_cache()（A v3.1.6 + v3.4.6），Phase 測試需要它
- back-compat 補 12 個 Phase 類別的 WPDO_ alias
- 移植 MigrationPhaseTest + MigrationPhaseRemainingTest（527 行）

測試隔離差異（B 的 unit bootstrap 會載入 Member_Fields / Post_Fields，
A 的不會）：MigrationPhaseRemainingTest 的 setUp 需額外清空 Entity_Registry
與 wpdo_register_entity_fields listener，否則 install_schema 會真的走進
dbDelta。MigrationPhaseTest 的 interface 斷言改用 TMDO_ 正式名稱
（PHP 無法 class_alias 介面，且該契約是核心內部擴充點）。

unit 451 / integration 398 GREEN

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TbG1keQQ7XBa7qMQY16KCY
This commit is contained in:
wpdev
2026-07-31 05:54:49 +08:00
parent f187ac5401
commit c46814ce83
21 changed files with 1698 additions and 513 deletions
Download Patch File Download Diff File Expand all files Collapse all files
includes/migration/class-tmdo-migration-orchestrator.php
+45 -511
View File
@@ -1,5 +1,4 @@
<?php
// phpcs:ignore WPDO.AntiEAV -- platform migration tool: WPDO v1->v2 legacy meta orchestration
/**
* One-click User Entity Migration Orchestrator.
*
@@ -11,15 +10,17 @@
* is 10-50× faster than per-row PHP loops. Per-row safe_unserialize fallback
* applies only to groups containing `json` fields (currently only `hp_user`).
*
* @package WP_Data_Optimizer
* @package TMDO
* @since 2.8.0
*/
// phpcs:ignore WPDO.AntiEAV -- platform migration tool: WPDO v1->v2 legacy meta orchestration
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
// phpcs:disable Squiz.Commenting.FunctionComment,Squiz.Commenting.VariableComment,Squiz.Commenting.ClassComment,WordPress.DB.PreparedSQL.NotPrepared,WordPress.DB.PreparedSQL.InterpolatedNotPrepared,WordPress.Security.EscapeOutput.ExceptionNotEscaped,WordPress.PHP.YodaConditions,Squiz.Commenting.InlineComment.InvalidEndChar -- Internal state-machine helpers and Throwable messages — not user output. SQL composed with sanitize_column_name() + $wpdb->prepare() values.
// phpcs:disable Squiz.Commenting.FunctionComment,Squiz.Commenting.VariableComment,Squiz.Commenting.ClassComment,WordPress.DB.PreparedSQL.InterpolatedNotPrepared,WordPress.Security.EscapeOutput.ExceptionNotEscaped,WordPress.PHP.YodaConditions,Squiz.Commenting.InlineComment.InvalidEndChar -- Internal state-machine helpers and Throwable messages — not user output. SQL composed with sanitize_column_name() + $wpdb->prepare() values.
/**
* One-click User Migration Orchestrator — drives the demote → backfill →
@@ -27,7 +28,7 @@ if ( ! defined( 'ABSPATH' ) ) {
*
* @since 2.8.0
*/
final class TMDO_Migration_Orchestrator {
class TMDO_Migration_Orchestrator {
const OPT_JOB = 'wpdo_migration_job';
const OPT_LOCK = 'wpdo_migration_lock';
@@ -78,14 +79,14 @@ final class TMDO_Migration_Orchestrator {
$eav_rows = self::count_eav_residue( $managed_keys );
$users = (int) $wpdb->get_var( "SELECT COUNT(*) FROM {$wpdb->users}" );
$usermeta = (int) $wpdb->get_var( "SELECT COUNT(*) FROM {$wpdb->usermeta}" );
$mode = TMDO_Mode_Manager::get( self::ENTITY_TYPE );
$mode = TMDO_Mode_Manager::get( static::ENTITY_TYPE );
$groups = array();
foreach ( TMDO_Entity_Registry::get_groups_for_type( self::ENTITY_TYPE ) as $group ) {
$keys = TMDO_Entity_Registry::get_group_keys( self::ENTITY_TYPE, $group );
foreach ( TMDO_Entity_Registry::get_groups_for_type( static::ENTITY_TYPE ) as $group ) {
$keys = TMDO_Entity_Registry::get_group_keys( static::ENTITY_TYPE, $group );
$has_json = self::group_has_json_field( $group );
$residue = $keys ? self::count_eav_residue( $keys ) : 0;
$flat_table = TMDO_Schema_Manager::get_table_name( self::ENTITY_TYPE, $group );
$flat_table = TMDO_Schema_Manager::get_table_name( static::ENTITY_TYPE, $group );
$flat_rows = TMDO_Schema_Manager::table_exists( $flat_table )
? (int) $wpdb->get_var( "SELECT COUNT(*) FROM `{$flat_table}`" )
: 0;
@@ -145,8 +146,8 @@ final class TMDO_Migration_Orchestrator {
$eav_rows = self::count_eav_residue( $managed_keys );
$groups_with_residue = 0;
foreach ( TMDO_Entity_Registry::get_groups_for_type( self::ENTITY_TYPE ) as $group ) {
$keys = TMDO_Entity_Registry::get_group_keys( self::ENTITY_TYPE, $group );
foreach ( TMDO_Entity_Registry::get_groups_for_type( static::ENTITY_TYPE ) as $group ) {
$keys = TMDO_Entity_Registry::get_group_keys( static::ENTITY_TYPE, $group );
if ( $keys && self::count_eav_residue( $keys ) > 0 ) {
++$groups_with_residue;
}
@@ -154,7 +155,7 @@ final class TMDO_Migration_Orchestrator {
$users = (int) $wpdb->get_var( "SELECT COUNT(*) FROM {$wpdb->users}" );
$usermeta = (int) $wpdb->get_var( "SELECT COUNT(*) FROM {$wpdb->usermeta}" );
$mode = TMDO_Mode_Manager::get( self::ENTITY_TYPE );
$mode = TMDO_Mode_Manager::get( static::ENTITY_TYPE );
$job_state = 'idle';
$job = get_option( self::OPT_JOB );
@@ -299,14 +300,11 @@ final class TMDO_Migration_Orchestrator {
}
$current = $job['phase'];
$method = 'phase_' . $current;
try {
if ( ! method_exists( __CLASS__, $method ) ) {
throw new \RuntimeException( "Unknown phase: {$current}" );
}
$result = self::{$method}( $job );
$phase_started = microtime( true );
$phase = self::make_phase( $current );
$result = $phase->execute( $job );
if ( 'in_progress' === ( $result['status'] ?? '' ) ) {
self::persist_job( $job );
@@ -324,7 +322,7 @@ final class TMDO_Migration_Orchestrator {
}
$next = self::next_phase( $current );
self::log( $job, sprintf( '✓ %s (%.2fs)', $current, microtime( true ) - ( $result['_started_at'] ?? microtime( true ) ) ) );
self::log( $job, sprintf( '✓ %s (%.2fs)', $current, microtime( true ) - $phase_started ) );
$job['phase'] = $next;
$job['phase_index'] = array_search( $next, self::PHASES, true );
$job['phase_progress'] = 0;
@@ -332,18 +330,7 @@ final class TMDO_Migration_Orchestrator {
$job['updated_at'] = time();
if ( 'completed' === $next ) {
$job['state'] = 'completed';
$job['completed_at'] = time();
$job['overall_progress'] = 100;
self::log(
$job,
sprintf(
'✅ Migration complete — ratio %s → %s (-%.0f%%)',
$job['metrics']['ratio_start'],
$job['metrics']['ratio_now'],
( $job['metrics']['ratio_start'] - $job['metrics']['ratio_now'] ) / max( $job['metrics']['ratio_start'], 0.01 ) * 100
)
);
self::make_phase( 'completed' )->execute( $job );
self::persist_job( $job );
self::release_lock();
self::bust_attention_cache();
@@ -396,12 +383,12 @@ final class TMDO_Migration_Orchestrator {
}
// Auto-rollback to safe state (dual_write) before clearing.
try {
$current_mode = TMDO_Mode_Manager::get( self::ENTITY_TYPE );
$current_mode = TMDO_Mode_Manager::get( static::ENTITY_TYPE );
if ( TMDO_Mode_Manager::MODE_AEAV_ONLY === $current_mode ) {
TMDO_Mode_Manager::set( self::ENTITY_TYPE, TMDO_Mode_Manager::MODE_SHADOW_READ );
TMDO_Mode_Manager::set( self::ENTITY_TYPE, TMDO_Mode_Manager::MODE_DUAL_WRITE );
TMDO_Mode_Manager::set( static::ENTITY_TYPE, TMDO_Mode_Manager::MODE_SHADOW_READ );
TMDO_Mode_Manager::set( static::ENTITY_TYPE, TMDO_Mode_Manager::MODE_DUAL_WRITE );
} elseif ( TMDO_Mode_Manager::MODE_SHADOW_READ === $current_mode ) {
TMDO_Mode_Manager::set( self::ENTITY_TYPE, TMDO_Mode_Manager::MODE_DUAL_WRITE );
TMDO_Mode_Manager::set( static::ENTITY_TYPE, TMDO_Mode_Manager::MODE_DUAL_WRITE );
}
} catch ( \Throwable $e ) {
// Logged but non-fatal.
@@ -480,405 +467,28 @@ final class TMDO_Migration_Orchestrator {
// Phases — each returns ['status' => 'ok'|'in_progress'|'error', 'message' => string]
// ─────────────────────────────────────────────────────────────────────
private static function phase_diagnose( array &$job ): array {
$preflight = self::preflight();
$job['metrics']['eav_rows_now'] = $preflight['eav_rows'];
$job['metrics']['ratio_now'] = $preflight['ratio'];
// ── Phase factory ─────────────────────────────────────────────────────────
self::log(
$job,
sprintf(
'Diagnose: %d EAV residue rows, %d users, ratio %s, mode %s',
$preflight['eav_rows'],
$preflight['users'],
(string) $preflight['ratio'],
$preflight['mode']
)
);
return array(
'status' => 'ok',
'message' => 'Diagnose complete',
private static function make_phase( string $name ): TMDO_Migration_Phase_Interface {
$map = array(
'diagnose' => TMDO_Phase_Diagnose::class,
'backup' => TMDO_Phase_Backup::class,
'demote' => TMDO_Phase_Demote::class,
'install_schema' => TMDO_Phase_Install_Schema::class,
'backfill_bulk' => TMDO_Phase_Backfill_Bulk::class,
'backfill_unserialize' => TMDO_Phase_Backfill_Unserialize::class,
'promote_shadow' => TMDO_Phase_Promote_Shadow::class,
'verify_sample' => TMDO_Phase_Verify_Sample::class,
'promote_aeav' => TMDO_Phase_Promote_Aeav::class,
'cleanup' => TMDO_Phase_Cleanup::class,
'completed' => TMDO_Phase_Completed::class,
);
if ( ! isset( $map[ $name ] ) ) {
throw new \RuntimeException( "Unknown phase: {$name}" );
}
return new $map[ $name ]( static::ENTITY_TYPE );
}
private static function phase_backup( array &$job ): array {
if ( empty( $job['options']['auto_backup'] ) ) {
self::log( $job, '↪ Backup skipped (auto_backup=false)' );
return array( 'status' => 'ok' );
}
$upload_dir = wp_upload_dir();
$backup_dir = trailingslashit( $upload_dir['basedir'] ) . self::BACKUP_DIR_REL;
if ( ! wp_mkdir_p( $backup_dir ) ) {
throw new \RuntimeException( "Cannot create backup directory: {$backup_dir}" );
}
// HTTP-level deny for Apache/IIS. Note: nginx silently ignores .htaccess —
// operators on nginx must add a `location ~ /wp-content/uploads/wpdo-backups/
// { deny all; }` block (logged in admin notice).
$htaccess = $backup_dir . '/.htaccess';
if ( ! file_exists( $htaccess ) ) {
file_put_contents( $htaccess, "Require all denied\n" );
@chmod( $htaccess, 0644 );
}
$webconfig = $backup_dir . '/web.config';
if ( ! file_exists( $webconfig ) ) {
file_put_contents(
$webconfig,
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<configuration><system.webServer><authorization><deny users=\"*\"/></authorization></system.webServer></configuration>\n"
);
@chmod( $webconfig, 0644 );
}
$index = $backup_dir . '/index.php';
if ( ! file_exists( $index ) ) {
file_put_contents( $index, "<?php // Silence is golden.\n" );
@chmod( $index, 0644 );
}
$filename = sprintf(
'wp_usermeta_%s_%s.sql',
gmdate( 'Ymd_His' ),
$job['job_id']
);
$backup_path = $backup_dir . '/' . $filename;
global $wpdb;
$rows = $wpdb->get_results(
"SELECT umeta_id, user_id, meta_key, meta_value FROM {$wpdb->usermeta} ORDER BY umeta_id ASC",
ARRAY_A
);
$fp = fopen( $backup_path, 'wb' );
if ( ! $fp ) {
throw new \RuntimeException( "Cannot open backup file for writing: {$backup_path}" );
}
// Owner-only read/write — backup contains user PII (emails, billing
// addresses, OAuth tokens, session blobs). Default umask leaks to
// other system users on shared hosts.
@chmod( $backup_path, 0600 );
fwrite( $fp, "-- WPDO migration backup of {$wpdb->usermeta}\n" );
fwrite( $fp, '-- Job: ' . $job['job_id'] . "\n" );
fwrite( $fp, '-- Generated: ' . gmdate( 'c' ) . "\n" );
fwrite( $fp, "-- Restore: mysql ... < this_file.sql\n\n" );
fwrite( $fp, "/*!40101 SET NAMES utf8mb4 */;\n" );
fwrite( $fp, "/*!40101 SET @OLD_SQL_MODE=@@SQL_MODE, SQL_MODE='NO_AUTO_VALUE_ON_ZERO' */;\n" );
fwrite( $fp, "SET FOREIGN_KEY_CHECKS=0;\n" );
fwrite( $fp, "LOCK TABLES `{$wpdb->usermeta}` WRITE;\n" );
$batch = array();
$count = 0;
foreach ( $rows as $row ) {
// UNHEX-encode meta_value: avoids ALL escape edge cases (binary,
// embedded NULs, non-UTF8, sql_mode mismatches at restore time).
// meta_key is %-bound through esc_sql which is sufficient for an
// ASCII-only key universe.
$batch[] = sprintf(
"(%d,%d,'%s',UNHEX('%s'))",
(int) $row['umeta_id'],
(int) $row['user_id'],
esc_sql( (string) $row['meta_key'] ),
bin2hex( (string) ( $row['meta_value'] ?? '' ) )
);
++$count;
if ( count( $batch ) >= 500 ) {
fwrite( $fp, "INSERT INTO `{$wpdb->usermeta}` (umeta_id,user_id,meta_key,meta_value) VALUES\n" . implode( ",\n", $batch ) . ";\n" );
$batch = array();
}
}
if ( $batch ) {
fwrite( $fp, "INSERT INTO `{$wpdb->usermeta}` (umeta_id,user_id,meta_key,meta_value) VALUES\n" . implode( ",\n", $batch ) . ";\n" );
}
fwrite( $fp, "UNLOCK TABLES;\n" );
fwrite( $fp, "SET FOREIGN_KEY_CHECKS=1;\n" );
fwrite( $fp, "/*!40101 SET SQL_MODE=@OLD_SQL_MODE */;\n" );
fclose( $fp );
$job['backup_path'] = $backup_path;
self::log(
$job,
sprintf(
'Backup written: %s (%d rows, %s, chmod 0600)',
$filename,
$count,
size_format( filesize( $backup_path ) )
)
);
// Best-effort web-server detection — log nginx warning so operator
// can add the manual location block (htaccess/web.config don't apply).
$server = isset( $_SERVER['SERVER_SOFTWARE'] ) ? strtolower( sanitize_text_field( wp_unslash( (string) $_SERVER['SERVER_SOFTWARE'] ) ) ) : '';
if ( str_contains( $server, 'nginx' ) ) {
self::log( $job, '⚠ nginx detected: add `location ~ /wp-content/uploads/wpdo-backups/ { deny all; }` to your nginx config — .htaccess does not apply.' );
}
return array( 'status' => 'ok' );
}
private static function phase_demote( array &$job ): array {
$current = TMDO_Mode_Manager::get( self::ENTITY_TYPE );
if ( TMDO_Mode_Manager::MODE_AEAV_ONLY !== $current ) {
self::log( $job, "↪ Demote skipped (mode is {$current}, not aeav_only)" );
return array( 'status' => 'ok' );
}
// Two-step demotion: aeav_only → shadow_read → dual_write.
// (Safe transition: demotion always allowed.)
$r = TMDO_Mode_Manager::set( self::ENTITY_TYPE, TMDO_Mode_Manager::MODE_SHADOW_READ );
if ( is_wp_error( $r ) ) {
throw new \RuntimeException( 'Demote step 1 failed: ' . $r->get_error_message() );
}
$r = TMDO_Mode_Manager::set( self::ENTITY_TYPE, TMDO_Mode_Manager::MODE_DUAL_WRITE );
if ( is_wp_error( $r ) ) {
throw new \RuntimeException( 'Demote step 2 failed: ' . $r->get_error_message() );
}
self::log( $job, 'Mode: aeav_only → dual_write (reads now go to EAV)' );
return array( 'status' => 'ok' );
}
private static function phase_install_schema( array &$job ): array {
do_action( 'wpdo_register_entity_fields', TMDO_Entity_Registry::class );
TMDO_Schema_Manager::process_pending_migrations();
// Verify all 9 expected tables exist.
$missing = array();
foreach ( TMDO_Entity_Registry::get_groups_for_type( self::ENTITY_TYPE ) as $group ) {
$table = TMDO_Schema_Manager::get_table_name( self::ENTITY_TYPE, $group );
if ( ! TMDO_Schema_Manager::table_exists( $table ) ) {
$missing[] = $group;
}
}
if ( $missing ) {
throw new \RuntimeException( 'Schema migration failed; missing tables: ' . implode( ',', $missing ) );
}
$count = count( TMDO_Entity_Registry::get_groups_for_type( self::ENTITY_TYPE ) );
self::log( $job, "Schema migration ok ({$count} flat tables verified)" );
return array( 'status' => 'ok' );
}
private static function phase_backfill_bulk( array &$job ): array {
if ( ! empty( $job['options']['dry_run'] ) ) {
self::log( $job, '↪ Backfill bulk skipped (dry_run)' );
return array( 'status' => 'ok' );
}
$total_groups = 0;
$total_rows = 0;
foreach ( TMDO_Entity_Registry::get_groups_for_type( self::ENTITY_TYPE ) as $group ) {
if ( self::group_has_json_field( $group ) ) {
continue; // handled in phase_backfill_unserialize
}
$rows = self::execute_bulk_pivot( $group );
$total_rows += $rows;
++$total_groups;
self::log( $job, sprintf( ' • bulk pivot %s: %d row(s)', $group, $rows ) );
}
self::log( $job, sprintf( 'Bulk backfill: %d groups, %d rows total', $total_groups, $total_rows ) );
// Update live ratio.
$preflight = self::preflight();
$job['metrics']['eav_rows_now'] = $preflight['eav_rows'];
$job['metrics']['ratio_now'] = $preflight['ratio'];
return array( 'status' => 'ok' );
}
private static function phase_backfill_unserialize( array &$job ): array {
if ( ! empty( $job['options']['dry_run'] ) ) {
self::log( $job, '↪ Backfill unserialize skipped (dry_run)' );
return array( 'status' => 'ok' );
}
$total_rows = 0;
foreach ( TMDO_Entity_Registry::get_groups_for_type( self::ENTITY_TYPE ) as $group ) {
if ( ! self::group_has_json_field( $group ) ) {
continue;
}
$result = TMDO_Entity_Migration_Engine::migrate_group(
self::ENTITY_TYPE,
$group,
array( 'sleep_ms' => 0 )
);
if ( ! empty( $result['error'] ) ) {
throw new \RuntimeException( "Row-by-row backfill {$group} failed: " . $result['error'] );
}
if ( ( $result['errors'] ?? 0 ) > 0 && 0 === ( $result['migrated'] ?? 0 ) ) {
throw new \RuntimeException( "All rows failed during {$group} backfill — see error_log" );
}
$total_rows += (int) ( $result['migrated'] ?? 0 );
self::log( $job, sprintf( ' • row-by-row %s: %d row(s)', $group, $result['migrated'] ?? 0 ) );
}
self::log( $job, sprintf( 'Row-by-row backfill: %d rows total', $total_rows ) );
return array( 'status' => 'ok' );
}
private static function phase_promote_shadow( array &$job ): array {
$current = TMDO_Mode_Manager::get( self::ENTITY_TYPE );
if ( TMDO_Mode_Manager::MODE_DUAL_WRITE === $current ) {
$r = TMDO_Mode_Manager::set( self::ENTITY_TYPE, TMDO_Mode_Manager::MODE_SHADOW_READ );
if ( is_wp_error( $r ) ) {
throw new \RuntimeException( 'Promote to shadow_read failed: ' . $r->get_error_message() );
}
self::log( $job, 'Mode: dual_write → shadow_read (verifying flat reads)' );
} else {
self::log( $job, "↪ Already at {$current}; skip promote_shadow" );
}
return array( 'status' => 'ok' );
}
private static function phase_verify_sample( array &$job ): array {
global $wpdb;
if ( ! empty( $job['options']['verify_24h'] ) ) {
// Operator opted into the 24-hour shadow-read window — pause here.
$elapsed = time() - ( $job['phase_started_at'] ?? time() );
if ( ! isset( $job['phase_started_at'] ) ) {
$job['phase_started_at'] = time();
self::log( $job, '⏸ 24h shadow_read window started — wizard will resume after window elapses.' );
return array( 'status' => 'in_progress' );
}
if ( $elapsed < DAY_IN_SECONDS ) {
return array( 'status' => 'in_progress' );
}
self::log( $job, '⏳ 24h shadow_read window complete; running sample compare' );
}
$strict = ! empty( $job['options']['verify_strict'] );
$users_total = (int) $wpdb->get_var( "SELECT COUNT(*) FROM {$wpdb->users}" );
$sample_size = $strict
? (int) max( self::VERIFY_SAMPLE_MIN, ceil( $users_total * self::VERIFY_SAMPLE_RATIO ) )
: 100;
$sample_size = min( $sample_size, $users_total );
$sample_ids = $wpdb->get_col(
$wpdb->prepare(
"SELECT ID FROM {$wpdb->users} ORDER BY RAND() LIMIT %d",
$sample_size
)
);
$diffs = 0;
$compared = 0;
$managed_keys = self::get_managed_keys();
foreach ( $sample_ids as $uid ) {
foreach ( $managed_keys as $key ) {
$eav = $wpdb->get_var(
$wpdb->prepare(
"SELECT meta_value FROM {$wpdb->usermeta} WHERE user_id = %d AND meta_key = %s LIMIT 1",
$uid,
$key
)
);
// Skip: no EAV source-of-truth to verify against (key already cleaned
// or never existed). The wizard's invariant only flags as DIFF the
// case where EAV has data but flat doesn't match it — that is the
// only real "backfill error".
if ( null === $eav || '' === $eav ) {
continue;
}
++$compared;
$flat = TMDO_Hook_Bus::direct_read( self::ENTITY_TYPE, (int) $uid, $key );
if ( ! self::values_loose_equal( $flat, $eav ) ) {
++$diffs;
if ( $diffs <= 3 ) {
self::log(
$job,
sprintf(
' ! diff uid=%d key=%s flat=%s eav=%s',
$uid,
$key,
is_scalar( $flat ) ? (string) $flat : gettype( $flat ),
is_scalar( $eav ) ? (string) $eav : gettype( $eav )
)
);
}
}
}
}
self::log(
$job,
sprintf(
'Verify: sampled %d users × %d keys = %d compares, %d diff(s)',
count( $sample_ids ),
count( $managed_keys ),
$compared,
$diffs
)
);
if ( $diffs > 0 ) {
throw new \RuntimeException(
sprintf(
'Verification found %d divergence(s) across %d compares — aborting before destructive cleanup.',
$diffs,
$compared
)
);
}
return array( 'status' => 'ok' );
}
private static function phase_promote_aeav( array &$job ): array {
$current = TMDO_Mode_Manager::get( self::ENTITY_TYPE );
if ( TMDO_Mode_Manager::MODE_AEAV_ONLY === $current ) {
self::log( $job, '↪ Already aeav_only' );
return array( 'status' => 'ok' );
}
$r = TMDO_Mode_Manager::set( self::ENTITY_TYPE, TMDO_Mode_Manager::MODE_AEAV_ONLY );
if ( is_wp_error( $r ) ) {
throw new \RuntimeException( 'Promote to aeav_only failed: ' . $r->get_error_message() );
}
self::log( $job, 'Mode: shadow_read → aeav_only (cutover complete)' );
return array( 'status' => 'ok' );
}
private static function phase_cleanup( array &$job ): array {
if ( ! empty( $job['options']['dry_run'] ) ) {
self::log( $job, '↪ Cleanup skipped (dry_run)' );
return array( 'status' => 'ok' );
}
// Hard guard: must be in aeav_only AND backup must exist (if requested).
$mode = TMDO_Mode_Manager::get( self::ENTITY_TYPE );
if ( TMDO_Mode_Manager::MODE_AEAV_ONLY !== $mode ) {
throw new \RuntimeException( "Refusing cleanup — mode is {$mode}, must be aeav_only" );
}
if ( ! empty( $job['options']['auto_backup'] ) && empty( $job['backup_path'] ) ) {
throw new \RuntimeException( 'Refusing cleanup — auto_backup requested but no backup_path on record' );
}
global $wpdb;
$keys = self::get_managed_keys();
if ( empty( $keys ) ) {
self::log( $job, '↪ No managed keys to clean' );
return array( 'status' => 'ok' );
}
$placeholders = implode( ',', array_fill( 0, count( $keys ), '%s' ) );
$deleted = (int) $wpdb->query(
$wpdb->prepare(
"DELETE FROM {$wpdb->usermeta} WHERE meta_key IN ({$placeholders})",
...$keys
)
);
// Refresh metrics.
$preflight = self::preflight();
$job['metrics']['eav_rows_now'] = $preflight['eav_rows'];
$job['metrics']['ratio_now'] = $preflight['ratio'];
self::log( $job, sprintf( 'Cleanup: deleted %d EAV row(s); ratio now %s', $deleted, (string) $preflight['ratio'] ) );
return array( 'status' => 'ok' );
}
// ─────────────────────────────────────────────────────────────────────
// Helpers
@@ -887,14 +497,14 @@ final class TMDO_Migration_Orchestrator {
/** Returns all meta_keys registered as entity fields for `user`. */
private static function get_managed_keys(): array {
$keys = array();
foreach ( TMDO_Entity_Registry::get_groups_for_type( self::ENTITY_TYPE ) as $group ) {
$keys = array_merge( $keys, TMDO_Entity_Registry::get_group_keys( self::ENTITY_TYPE, $group ) );
foreach ( TMDO_Entity_Registry::get_groups_for_type( static::ENTITY_TYPE ) as $group ) {
$keys = array_merge( $keys, TMDO_Entity_Registry::get_group_keys( static::ENTITY_TYPE, $group ) );
}
return array_values( array_unique( $keys ) );
}
private static function group_has_json_field( string $group ): bool {
foreach ( TMDO_Entity_Registry::get_group_fields( self::ENTITY_TYPE, $group ) as $field ) {
foreach ( TMDO_Entity_Registry::get_group_fields( static::ENTITY_TYPE, $group ) as $field ) {
if ( 'json' === ( $field['type'] ?? '' ) ) {
return true;
}
@@ -919,82 +529,6 @@ final class TMDO_Migration_Orchestrator {
);
}
/**
* Single-statement bulk pivot for a text-only group.
*
* @param string $group Entity group name.
* @return int Affected rows.
* @throws \RuntimeException If $wpdb->query() fails.
*/
private static function execute_bulk_pivot( string $group ): int {
global $wpdb;
$fields = TMDO_Entity_Registry::get_group_fields( self::ENTITY_TYPE, $group );
if ( empty( $fields ) ) {
return 0;
}
$adapter = TMDO_Entity_Registry::get_adapter( self::ENTITY_TYPE );
$id_col = $adapter->get_entity_id_column();
$table = TMDO_Schema_Manager::get_table_name( self::ENTITY_TYPE, $group );
$select_cases = array();
$update_cols = array();
$col_names = array();
$keys = array();
foreach ( $fields as $f ) {
$key = $f['key'];
$col = TMDO_Schema_Manager::sanitize_column_name( $key );
$keys[] = $key;
$col_names[] = "`{$col}`";
// MAX(CASE WHEN meta_key='...' THEN meta_value END)
$select_cases[] = $wpdb->prepare(
"MAX(CASE WHEN um.meta_key = %s THEN um.meta_value END) AS `{$col}`",
$key
);
$update_cols[] = "`{$col}` = COALESCE(VALUES(`{$col}`), `{$col}`)";
}
$placeholders = implode( ',', array_fill( 0, count( $keys ), '%s' ) );
$sql = sprintf(
'INSERT INTO `%s` (`%s`, %s)
SELECT um.user_id, %s
FROM `%s` um
WHERE um.meta_key IN (%s)
GROUP BY um.user_id
ON DUPLICATE KEY UPDATE %s',
$table,
$id_col,
implode( ', ', $col_names ),
implode( ', ', $select_cases ),
$wpdb->usermeta,
$placeholders,
implode( ', ', $update_cols )
);
// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared,WordPress.DB.PreparedSQL.InterpolatedNotPrepared -- pivot SQL composed from registry-validated identifiers + prepared values inside CASE/IN.
$result = $wpdb->query( $wpdb->prepare( $sql, ...$keys ) );
if ( false === $result ) {
throw new \RuntimeException( "Bulk pivot failed for group {$group}: " . $wpdb->last_error );
}
return (int) $result;
}
private static function values_loose_equal( $a, $b ): bool {
if ( null === $a && null === $b ) {
return true;
}
if ( null === $a || null === $b ) {
$other = null === $a ? $b : $a;
return '' === $other || array() === $other || 0 === $other || '0' === $other;
}
if ( is_array( $a ) || is_array( $b ) ) {
return wp_json_encode( $a ) === wp_json_encode( $b );
}
return (string) $a === (string) $b;
}
private static function next_phase( string $current ): string {
$idx = array_search( $current, self::PHASES, true );
@@ -1072,12 +606,12 @@ final class TMDO_Migration_Orchestrator {
// Auto-rollback: only if mode is currently aeav_only AND we haven't reached cleanup yet.
try {
$current = TMDO_Mode_Manager::get( self::ENTITY_TYPE );
$current = TMDO_Mode_Manager::get( static::ENTITY_TYPE );
$phase = $job['phase'] ?? '';
$pre_cleanup = ! in_array( $phase, array( 'cleanup', 'completed' ), true );
if ( $pre_cleanup && TMDO_Mode_Manager::MODE_AEAV_ONLY === $current ) {
TMDO_Mode_Manager::set( self::ENTITY_TYPE, TMDO_Mode_Manager::MODE_SHADOW_READ );
TMDO_Mode_Manager::set( self::ENTITY_TYPE, TMDO_Mode_Manager::MODE_DUAL_WRITE );
TMDO_Mode_Manager::set( static::ENTITY_TYPE, TMDO_Mode_Manager::MODE_SHADOW_READ );
TMDO_Mode_Manager::set( static::ENTITY_TYPE, TMDO_Mode_Manager::MODE_DUAL_WRITE );
self::log( $job, '↩ Auto-rolled back to dual_write (reads safe)' );
}
} catch ( \Throwable $inner ) {