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/class-tmdo-back-compat.php
+12
View File
@@ -113,6 +113,18 @@ $tmdo_class_aliases = array(
'TMDO_Zone_Cold' => 'WPDO_Zone_Cold',
'TMDO_Zone_Router' => 'WPDO_Zone_Router',
'TMDO_Routing_Predicate' => 'WPDO_Routing_Predicate',
'TMDO_Migration_Phase_Base' => 'WPDO_Migration_Phase_Base',
'TMDO_Phase_Diagnose' => 'WPDO_Phase_Diagnose',
'TMDO_Phase_Backup' => 'WPDO_Phase_Backup',
'TMDO_Phase_Demote' => 'WPDO_Phase_Demote',
'TMDO_Phase_Install_Schema' => 'WPDO_Phase_Install_Schema',
'TMDO_Phase_Backfill_Bulk' => 'WPDO_Phase_Backfill_Bulk',
'TMDO_Phase_Backfill_Unserialize' => 'WPDO_Phase_Backfill_Unserialize',
'TMDO_Phase_Promote_Shadow' => 'WPDO_Phase_Promote_Shadow',
'TMDO_Phase_Verify_Sample' => 'WPDO_Phase_Verify_Sample',
'TMDO_Phase_Promote_Aeav' => 'WPDO_Phase_Promote_Aeav',
'TMDO_Phase_Cleanup' => 'WPDO_Phase_Cleanup',
'TMDO_Phase_Completed' => 'WPDO_Phase_Completed',
'TMDO_Zone_Archive' => 'WPDO_Zone_Archive',
'TMDO_Interceptor_Base' => 'WPDO_Interceptor_Base',
'TMDO_Query_Interceptor_Base' => 'WPDO_Query_Interceptor_Base',
includes/engine/class-tmdo-schema-manager.php
+25 -2
View File
@@ -18,6 +18,9 @@ defined( 'ABSPATH' ) || exit;
final class TMDO_Schema_Manager {
/** Request-scoped cache for table_exists() — prevents repeated SHOW TABLES per request. */
private static array $table_exists_cache = array();
/**
* WordPress 邏輯型別 → MySQL 實體型別映射
*/
@@ -145,6 +148,9 @@ final class TMDO_Schema_Manager {
// dbDelta 自動處理建表／ALTER TABLE
$dbdelta_result = dbDelta( $sql );
// Bust the request-scoped table_exists cache so subsequent calls see the new table.
self::$table_exists_cache[ $table ] = true;
// 記錄 Schema 版本與定義
self::store_schema_metadata( $entity_type, $group_name, $schema_hash, $field_definitions );
@@ -284,8 +290,25 @@ final class TMDO_Schema_Manager {
*/
public static function table_exists( string $table_name ): bool {
global $wpdb;
$result = $wpdb->get_var( $wpdb->prepare( 'SHOW TABLES LIKE %s', $table_name ) );
return $result === $table_name;
if ( isset( self::$table_exists_cache[ $table_name ] ) ) {
return self::$table_exists_cache[ $table_name ];
}
$result = $wpdb->get_var( $wpdb->prepare( 'SHOW TABLES LIKE %s', $table_name ) );
self::$table_exists_cache[ $table_name ] = $result === $table_name;
return self::$table_exists_cache[ $table_name ];
}
/**
* Clear the request-scoped table-exists cache.
*
* Mirrors TMDO_Routing_Predicate::flush_cache(): call in test setUp to isolate
* cases. In production the cache is correct for a request lifetime; tests that
* create then drop flat tables across classes must reset it so a stale `true`
* does not survive after a table is dropped.
*/
public static function flush_table_exists_cache(): void {
self::$table_exists_cache = array();
}
/**
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 ) {
includes/migration/class-tmdo-migration-phase-base.php
+166
View File
@@ -0,0 +1,166 @@
<?php
/**
* Shared helpers for all migration phase Strategy objects.
*
* @package TMDO
* @since 3.0.1
*/
// phpcs:disable Squiz.Commenting.FunctionComment,WordPress.DB.PreparedSQL.NotPrepared,WordPress.DB.PreparedSQL.InterpolatedNotPrepared,WordPress.PHP.YodaConditions,WordPress.Security.EscapeOutput.OutputNotEscaped -- Internal helpers; SQL composed from registry-validated identifiers; exception messages not echoed.
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
/**
* Shared helpers for all migration phase Strategy objects.
*
* Concrete phases extend this class, receive the entity type at construction,
* and implement execute(). All database helpers delegate to
* TMDO_Entity_Registry / TMDO_Schema_Manager so the entity type is the only
* injection point needed for unit tests.
*/
abstract class TMDO_Migration_Phase_Base implements TMDO_Migration_Phase_Interface {
const MAX_LOG_LINES = 50;
/**
* Entity type this phase operates on (e.g. 'user', 'post').
*
* @var string
*/
protected string $entity_type;
public function __construct( string $entity_type ) {
$this->entity_type = $entity_type;
}
// ── Logging ───────────────────────────────────────────────────────────────
protected function log( array &$job, string $message ): void {
$line = '[' . gmdate( 'H:i:s' ) . '] ' . $message;
$job['log'][] = $line;
if ( count( $job['log'] ) > self::MAX_LOG_LINES ) {
$job['log'] = array_slice( $job['log'], -self::MAX_LOG_LINES );
}
$job['updated_at'] = time();
}
// ── Registry helpers ──────────────────────────────────────────────────────
protected function get_managed_keys(): array {
$keys = array();
foreach ( TMDO_Entity_Registry::get_groups_for_type( $this->entity_type ) as $group ) {
$keys = array_merge( $keys, TMDO_Entity_Registry::get_group_keys( $this->entity_type, $group ) );
}
return array_values( array_unique( $keys ) );
}
protected function group_has_json_field( string $group ): bool {
foreach ( TMDO_Entity_Registry::get_group_fields( $this->entity_type, $group ) as $field ) {
if ( 'json' === ( $field['type'] ?? '' ) ) {
return true;
}
}
return false;
}
// ── DB helpers ────────────────────────────────────────────────────────────
/** Count EAV rows for the given meta keys (or all managed keys if empty). */
protected function count_eav_residue( array $keys = array() ): int {
global $wpdb;
if ( empty( $keys ) ) {
$keys = $this->get_managed_keys();
}
if ( empty( $keys ) ) {
return 0;
}
$adapter = TMDO_Entity_Registry::get_adapter( $this->entity_type );
$meta_table = $adapter->get_native_meta_table();
$placeholders = implode( ',', array_fill( 0, count( $keys ), '%s' ) );
return (int) $wpdb->get_var(
$wpdb->prepare( "SELECT COUNT(*) FROM `{$meta_table}` WHERE meta_key IN ({$placeholders})", ...$keys )
);
}
/**
* Bulk pivot for a text-only group via INSERT … SELECT … GROUP BY …
* ON DUPLICATE KEY UPDATE.
*
* @param string $group Entity group to pivot.
* @return int Number of rows affected.
* @throws \RuntimeException On DB failure.
*/
protected function execute_bulk_pivot( string $group ): int {
global $wpdb;
$fields = TMDO_Entity_Registry::get_group_fields( $this->entity_type, $group );
if ( empty( $fields ) ) {
return 0;
}
$adapter = TMDO_Entity_Registry::get_adapter( $this->entity_type );
$id_col = $adapter->get_entity_id_column();
$meta_table = $adapter->get_native_meta_table();
$table = TMDO_Schema_Manager::get_table_name( $this->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}`";
$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 ),
$meta_table,
$placeholders,
implode( ', ', $update_cols )
);
$result = $wpdb->query( $wpdb->prepare( $sql, ...$keys ) );
if ( false === $result ) {
// phpcs:ignore WordPress.Security.EscapeOutput -- Exception message not echoed to browser.
throw new \RuntimeException( 'Bulk pivot failed for group ' . $group . ': ' . $wpdb->last_error );
}
return (int) $result;
}
/** Loose equality check for EAV vs flat value comparison (null/empty/scalar). */
protected 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;
}
}
includes/migration/interface-migration-phase.php
+37
View File
@@ -0,0 +1,37 @@
<?php
/**
* Contract for a single migration phase (Strategy pattern).
*
* @package TMDO
* @since 3.0.1
*/
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
/**
* Contract for a single migration phase (Strategy pattern).
*
* Each phase is idempotent — re-entering returns ok if the desired state is
* already achieved. The orchestrator never calls execute() on a phase that
* has already returned 'ok'; it only re-enters on 'in_progress'.
*/
interface TMDO_Migration_Phase_Interface {
/** Short slug matching the PHASES constant entry (e.g. 'backfill_bulk'). */
public function name(): string;
/**
* Run the phase.
*
* @param array $job Job array passed by reference — phase may append log
* lines and update metrics fields.
* @return array{status: 'ok'|'in_progress'|'done', message?: string}
* 'ok' — phase finished, advance to next.
* 'in_progress' — phase needs another tick (e.g. 24h window).
* 'done' — terminal phase completed (completed phase only).
* @throws \RuntimeException On unrecoverable failure; orchestrator catches.
*/
public function execute( array &$job ): array;
}
includes/migration/phases/class-tmdo-phase-backfill-bulk.php
+62
View File
@@ -0,0 +1,62 @@
<?php
/**
* Migration phase: bulk pivot text-only meta groups via INSERT … SELECT.
*
* @package TMDO
* @since 3.0.1
*/
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
/**
* Iterates all registered groups for the entity type and pivots each
* text-only group in a single INSERT … SELECT … ON DUPLICATE KEY UPDATE.
*/
class TMDO_Phase_Backfill_Bulk extends TMDO_Migration_Phase_Base {
/**
* Returns the phase slug.
*
* @return string
*/
public function name(): string {
return 'backfill_bulk';
}
/**
* Executes the phase.
*
* @param array $job Job array (by reference).
* @return array{status: string}
* @throws \RuntimeException On DB pivot failure.
*/
public function execute( array &$job ): array {
if ( ! empty( $job['options']['dry_run'] ) ) {
$this->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( $this->entity_type ) as $group ) {
if ( $this->group_has_json_field( $group ) ) {
continue; // Handled in backfill_unserialize.
}
$rows = $this->execute_bulk_pivot( $group );
$total_rows += $rows;
++$total_groups;
$this->log( $job, sprintf( ' • bulk pivot %s: %d row(s)', $group, $rows ) );
}
$this->log( $job, sprintf( 'Bulk backfill: %d groups, %d rows total', $total_groups, $total_rows ) );
$preflight = TMDO_Migration_Orchestrator::preflight();
$job['metrics']['eav_rows_now'] = $preflight['eav_rows'];
$job['metrics']['ratio_now'] = $preflight['ratio'];
return array( 'status' => 'ok' );
}
}
includes/migration/phases/class-tmdo-phase-backfill-unserialize.php
+69
View File
@@ -0,0 +1,69 @@
<?php
/**
* Migration phase: row-by-row backfill for groups with JSON/serialized fields.
*
* @package TMDO
* @since 3.0.1
*/
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
/**
* Uses TMDO_Entity_Migration_Engine for groups whose fields contain JSON type,
* which cannot be bulk-pivoted via INSERT … SELECT.
*/
class TMDO_Phase_Backfill_Unserialize extends TMDO_Migration_Phase_Base {
/**
* Returns the phase slug.
*
* @return string
*/
public function name(): string {
return 'backfill_unserialize';
}
/**
* Executes the phase.
*
* @param array $job Job array (by reference).
* @return array{status: string}
* @throws \RuntimeException On migration engine failure.
*/
public function execute( array &$job ): array {
if ( ! empty( $job['options']['dry_run'] ) ) {
$this->log( $job, '↪ Backfill unserialize skipped (dry_run)' );
return array( 'status' => 'ok' );
}
$total_rows = 0;
foreach ( TMDO_Entity_Registry::get_groups_for_type( $this->entity_type ) as $group ) {
if ( ! $this->group_has_json_field( $group ) ) {
continue; // Handled in backfill_bulk.
}
$result = TMDO_Entity_Migration_Engine::migrate_group(
$this->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 );
$this->log( $job, sprintf( ' • row-by-row %s: %d row(s)', $group, $result['migrated'] ?? 0 ) );
}
$this->log( $job, sprintf( 'Row-by-row backfill: %d rows total', $total_rows ) );
return array( 'status' => 'ok' );
}
}
includes/migration/phases/class-tmdo-phase-backup.php
+158
View File
@@ -0,0 +1,158 @@
<?php
/**
* Migration phase: back up the native meta table before destructive cleanup.
*
* @package TMDO
* @since 3.0.1
*/
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
/**
* Writes a mysqldump-style SQL file of the usermeta table to wp-content/uploads/wpdo-backups/.
*/
class TMDO_Phase_Backup extends TMDO_Migration_Phase_Base {
/**
* Relative path under wp-content/uploads/ for backup files.
*
* @var string
*/
const BACKUP_DIR_REL = 'wpdo-backups';
/**
* Returns the phase slug.
*
* @return string
*/
public function name(): string {
return 'backup';
}
/**
* Executes the phase.
*
* @param array $job Job array (by reference).
* @return array{status: string}
* @throws \RuntimeException If backup directory or file cannot be created.
*/
public function execute( array &$job ): array {
if ( empty( $job['options']['auto_backup'] ) ) {
$this->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}" );
}
$this->write_web_deny_files( $backup_dir );
$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", // phpcs:ignore WPDO.AntiEAV.no-direct-usermeta-select -- migration backup: must read raw usermeta to create full SQL dump before schema change
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).
@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 ( (array) $rows as $row ) {
// UNHEX-encode meta_value: avoids escape edge cases (binary, embedded
// NULs, non-UTF8, sql_mode mismatches at restore time).
$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;
$this->log(
$job,
sprintf(
'Backup written: %s (%d rows, %s, chmod 0600)',
$filename,
$count,
size_format( filesize( $backup_path ) )
)
);
$server = isset( $_SERVER['SERVER_SOFTWARE'] )
? strtolower( sanitize_text_field( wp_unslash( (string) $_SERVER['SERVER_SOFTWARE'] ) ) )
: '';
if ( str_contains( $server, 'nginx' ) ) {
$this->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' );
}
/**
* Writes .htaccess, web.config, and index.php deny files into the backup directory.
*
* @param string $backup_dir Absolute path to the backup directory.
* @return void
*/
private function write_web_deny_files( string $backup_dir ): void {
$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 );
}
}
}
includes/migration/phases/class-tmdo-phase-cleanup.php
+71
View File
@@ -0,0 +1,71 @@
<?php
/**
* Migration phase: remove managed keys from the native meta table.
*
* @package TMDO
* @since 3.0.1
*/
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
/**
* Deletes all managed meta keys from the EAV table after verifying aeav_only mode.
*/
class TMDO_Phase_Cleanup extends TMDO_Migration_Phase_Base {
/**
* Returns the phase slug.
*
* @return string
*/
public function name(): string {
return 'cleanup';
}
/**
* Executes the phase.
*
* @param array $job Job array (by reference).
* @return array{status: string}
* @throws \RuntimeException If mode is not aeav_only or backup is missing.
*/
public function execute( array &$job ): array {
global $wpdb;
if ( ! empty( $job['options']['dry_run'] ) ) {
$this->log( $job, '↪ Cleanup skipped (dry_run)' );
return array( 'status' => 'ok' );
}
$mode = TMDO_Mode_Manager::get( $this->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' );
}
$keys = $this->get_managed_keys();
if ( empty( $keys ) ) {
$this->log( $job, '↪ No managed keys to clean' );
return array( 'status' => 'ok' );
}
$adapter = TMDO_Entity_Registry::get_adapter( $this->entity_type );
$meta_table = $adapter->get_native_meta_table();
$placeholders = implode( ',', array_fill( 0, count( $keys ), '%s' ) );
$deleted = (int) $wpdb->query(
$wpdb->prepare( "DELETE FROM `{$meta_table}` WHERE meta_key IN ({$placeholders})", ...$keys )
);
$preflight = TMDO_Migration_Orchestrator::preflight();
$job['metrics']['eav_rows_now'] = $preflight['eav_rows'];
$job['metrics']['ratio_now'] = $preflight['ratio'];
$this->log( $job, sprintf( 'Cleanup: deleted %d EAV row(s); ratio now %s', $deleted, (string) $preflight['ratio'] ) );
return array( 'status' => 'ok' );
}
}
includes/migration/phases/class-tmdo-phase-completed.php
+53
View File
@@ -0,0 +1,53 @@
<?php
/**
* Migration phase: terminal phase marking the job as successfully completed.
*
* @package TMDO
* @since 3.0.1
*/
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
/**
* Terminal phase — marks the job as successfully completed.
*
* Returns 'done' (instead of 'ok') so tick() knows to release the lock and
* flush the attention cache without scheduling another tick.
*/
class TMDO_Phase_Completed extends TMDO_Migration_Phase_Base {
/**
* Returns the phase slug.
*
* @return string
*/
public function name(): string {
return 'completed';
}
/**
* Executes the phase.
*
* @param array $job Job array (by reference).
* @return array{status: 'done'}
*/
public function execute( array &$job ): array {
$job['state'] = 'completed';
$job['completed_at'] = time();
$job['overall_progress'] = 100;
$this->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
)
);
return array( 'status' => 'done' );
}
}
includes/migration/phases/class-tmdo-phase-demote.php
+57
View File
@@ -0,0 +1,57 @@
<?php
/**
* Migration phase: demote entity mode from aeav_only back to dual_write.
*
* @package TMDO
* @since 3.0.1
*/
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
/**
* Two-step mode demotion: aeav_only → shadow_read → dual_write.
*/
class TMDO_Phase_Demote extends TMDO_Migration_Phase_Base {
/**
* Returns the phase slug.
*
* @return string
*/
public function name(): string {
return 'demote';
}
/**
* Executes the phase.
*
* @param array $job Job array (by reference).
* @return array{status: string}
* @throws \RuntimeException If mode transition fails.
*/
public function execute( array &$job ): array {
$current = TMDO_Mode_Manager::get( $this->entity_type );
if ( TMDO_Mode_Manager::MODE_AEAV_ONLY !== $current ) {
$this->log( $job, "↪ Demote skipped (mode is {$current}, not aeav_only)" );
return array( 'status' => 'ok' );
}
// Two-step demotion: aeav_only → shadow_read → dual_write.
$r = TMDO_Mode_Manager::set( $this->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( $this->entity_type, TMDO_Mode_Manager::MODE_DUAL_WRITE );
if ( is_wp_error( $r ) ) {
throw new \RuntimeException( 'Demote step 2 failed: ' . $r->get_error_message() );
}
$this->log( $job, 'Mode: aeav_only → dual_write (reads now go to EAV)' );
return array( 'status' => 'ok' );
}
}
includes/migration/phases/class-tmdo-phase-diagnose.php
+54
View File
@@ -0,0 +1,54 @@
<?php
/**
* Migration phase: diagnose current entity state.
*
* @package TMDO
* @since 3.0.1
*/
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
/**
* Reads preflight metrics and records them in the job array.
*/
class TMDO_Phase_Diagnose extends TMDO_Migration_Phase_Base {
/**
* Returns the phase slug.
*
* @return string
*/
public function name(): string {
return 'diagnose';
}
/**
* Executes the phase.
*
* @param array $job Job array (by reference).
* @return array{status: string, message?: string}
*/
public function execute( array &$job ): array {
$preflight = TMDO_Migration_Orchestrator::preflight();
$job['metrics']['eav_rows_now'] = $preflight['eav_rows'];
$job['metrics']['ratio_now'] = $preflight['ratio'];
$this->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',
);
}
}
includes/migration/phases/class-tmdo-phase-install-schema.php
+55
View File
@@ -0,0 +1,55 @@
<?php
/**
* Migration phase: install flat schema tables for the entity type.
*
* @package TMDO
* @since 3.0.1
*/
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
/**
* Fires wpdo_register_entity_fields, runs schema migrations, verifies all tables exist.
*/
class TMDO_Phase_Install_Schema extends TMDO_Migration_Phase_Base {
/**
* Returns the phase slug.
*
* @return string
*/
public function name(): string {
return 'install_schema';
}
/**
* Executes the phase.
*
* @param array $job Job array (by reference).
* @return array{status: string}
* @throws \RuntimeException If any required tables are missing after migration.
*/
public function execute( array &$job ): array {
do_action( 'wpdo_register_entity_fields', TMDO_Entity_Registry::class );
TMDO_Schema_Manager::process_pending_migrations();
$missing = array();
foreach ( TMDO_Entity_Registry::get_groups_for_type( $this->entity_type ) as $group ) {
$table = TMDO_Schema_Manager::get_table_name( $this->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( $this->entity_type ) );
$this->log( $job, "Schema migration ok ({$count} flat tables verified)" );
return array( 'status' => 'ok' );
}
}
includes/migration/phases/class-tmdo-phase-promote-aeav.php
+51
View File
@@ -0,0 +1,51 @@
<?php
/**
* Migration phase: promote entity mode to aeav_only (cutover complete).
*
* @package TMDO
* @since 3.0.1
*/
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
/**
* Transitions mode from shadow_read → aeav_only.
*/
class TMDO_Phase_Promote_Aeav extends TMDO_Migration_Phase_Base {
/**
* Returns the phase slug.
*
* @return string
*/
public function name(): string {
return 'promote_aeav';
}
/**
* Executes the phase.
*
* @param array $job Job array (by reference).
* @return array{status: string}
* @throws \RuntimeException If mode transition fails.
*/
public function execute( array &$job ): array {
$current = TMDO_Mode_Manager::get( $this->entity_type );
if ( TMDO_Mode_Manager::MODE_AEAV_ONLY === $current ) {
$this->log( $job, '↪ Already aeav_only' );
return array( 'status' => 'ok' );
}
$r = TMDO_Mode_Manager::set( $this->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() );
}
$this->log( $job, 'Mode: shadow_read → aeav_only (cutover complete)' );
return array( 'status' => 'ok' );
}
}
includes/migration/phases/class-tmdo-phase-promote-shadow.php
+50
View File
@@ -0,0 +1,50 @@
<?php
/**
* Migration phase: promote entity mode to shadow_read.
*
* @package TMDO
* @since 3.0.1
*/
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
/**
* Transitions mode from dual_write → shadow_read (flat table serves reads).
*/
class TMDO_Phase_Promote_Shadow extends TMDO_Migration_Phase_Base {
/**
* Returns the phase slug.
*
* @return string
*/
public function name(): string {
return 'promote_shadow';
}
/**
* Executes the phase.
*
* @param array $job Job array (by reference).
* @return array{status: string}
* @throws \RuntimeException If mode transition fails.
*/
public function execute( array &$job ): array {
$current = TMDO_Mode_Manager::get( $this->entity_type );
if ( TMDO_Mode_Manager::MODE_DUAL_WRITE === $current ) {
$r = TMDO_Mode_Manager::set( $this->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() );
}
$this->log( $job, 'Mode: dual_write → shadow_read (verifying flat reads)' );
} else {
$this->log( $job, "↪ Already at {$current}; skip promote_shadow" );
}
return array( 'status' => 'ok' );
}
}
includes/migration/phases/class-tmdo-phase-verify-sample.php
+140
View File
@@ -0,0 +1,140 @@
<?php
/**
* Migration phase: sample-verify flat table vs EAV for data integrity.
*
* @package TMDO
* @since 3.0.1
*/
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
/**
* Samples a subset of entities and compares flat vs EAV values.
* Aborts with RuntimeException if any divergences are found.
*/
class TMDO_Phase_Verify_Sample extends TMDO_Migration_Phase_Base {
/**
* Minimum sample size regardless of total entity count.
*
* @var int
*/
const VERIFY_SAMPLE_MIN = 500;
/**
* Fraction of total entities to sample in strict mode.
*
* @var float
*/
const VERIFY_SAMPLE_RATIO = 0.10;
/**
* Returns the phase slug.
*
* @return string
*/
public function name(): string {
return 'verify_sample';
}
/**
* Executes the phase.
*
* @param array $job Job array (by reference).
* @return array{status: string}
* @throws \RuntimeException If verification divergences are found.
*/
public function execute( array &$job ): array {
global $wpdb;
if ( ! empty( $job['options']['verify_24h'] ) ) {
$elapsed = time() - ( $job['phase_started_at'] ?? time() );
if ( ! isset( $job['phase_started_at'] ) ) {
$job['phase_started_at'] = time();
$this->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' );
}
$this->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 = $this->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", // phpcs:ignore WPDO.AntiEAV.no-direct-usermeta-select -- verify phase: must compare EAV source against flat table to confirm migration correctness
$uid,
$key
)
);
// Skip keys with no EAV source-of-truth — only flag when EAV has data
// but flat doesn't match (real backfill error).
if ( null === $eav || '' === $eav ) {
continue;
}
++$compared;
$flat = TMDO_Hook_Bus::direct_read( $this->entity_type, (int) $uid, $key );
if ( ! $this->values_loose_equal( $flat, $eav ) ) {
++$diffs;
if ( $diffs <= 3 ) {
$this->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 )
)
);
}
}
}
}
$this->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' );
}
}