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
2meet-data-optimizer.php
+13
View File
@@ -236,6 +236,19 @@ require_once TMDO_PATH . 'includes/engine/class-tmdo-schema-manager.php';
require_once TMDO_PATH . 'includes/engine/class-tmdo-entity-registry.php';
require_once TMDO_PATH . 'includes/engine/class-tmdo-entity-migration-engine.php';
require_once TMDO_PATH . 'includes/engine/class-tmdo-entity-health.php';
require_once TMDO_PATH . 'includes/migration/interface-migration-phase.php';
require_once TMDO_PATH . 'includes/migration/class-tmdo-migration-phase-base.php';
require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-diagnose.php';
require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-backup.php';
require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-demote.php';
require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-install-schema.php';
require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-backfill-bulk.php';
require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-backfill-unserialize.php';
require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-promote-shadow.php';
require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-verify-sample.php';
require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-promote-aeav.php';
require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-cleanup.php';
require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-completed.php';
require_once TMDO_PATH . 'includes/migration/class-tmdo-migration-orchestrator.php';
require_once TMDO_PATH . 'includes/migration/class-tmdo-post-migration.php';
add_action( TMDO_Migration_Orchestrator::CRON_HOOK, array( 'TMDO_Migration_Orchestrator', 'cron_tick' ) );
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' );
}
}
tests/bootstrap.php
+13
View File
@@ -600,6 +600,19 @@ require_once TMDO_PATH . 'includes/adapters/class-tmdo-adapter-term.php';
require_once TMDO_PATH . 'includes/adapters/class-tmdo-adapter-comment.php';
// Migration Orchestrator (needs Entity_Registry).
require_once TMDO_PATH . 'includes/migration/interface-migration-phase.php';
require_once TMDO_PATH . 'includes/migration/class-tmdo-migration-phase-base.php';
require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-diagnose.php';
require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-backup.php';
require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-demote.php';
require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-install-schema.php';
require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-backfill-bulk.php';
require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-backfill-unserialize.php';
require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-promote-shadow.php';
require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-verify-sample.php';
require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-promote-aeav.php';
require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-cleanup.php';
require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-completed.php';
require_once TMDO_PATH . 'includes/migration/class-tmdo-migration-orchestrator.php';
require_once TMDO_PATH . 'includes/migration/class-tmdo-post-migration.php';
tests/integration/bootstrap.php
+13
View File
@@ -569,6 +569,19 @@ require_once TMDO_PATH . 'includes/adapters/class-tmdo-adapter-post.php';
require_once TMDO_PATH . 'includes/adapters/class-tmdo-adapter-user.php';
require_once TMDO_PATH . 'includes/adapters/class-tmdo-adapter-term.php';
require_once TMDO_PATH . 'includes/adapters/class-tmdo-adapter-comment.php';
require_once TMDO_PATH . 'includes/migration/interface-migration-phase.php';
require_once TMDO_PATH . 'includes/migration/class-tmdo-migration-phase-base.php';
require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-diagnose.php';
require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-backup.php';
require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-demote.php';
require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-install-schema.php';
require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-backfill-bulk.php';
require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-backfill-unserialize.php';
require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-promote-shadow.php';
require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-verify-sample.php';
require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-promote-aeav.php';
require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-cleanup.php';
require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-completed.php';
require_once TMDO_PATH . 'includes/migration/class-tmdo-migration-orchestrator.php';
require_once TMDO_PATH . 'includes/migration/class-tmdo-post-migration.php';
require_once TMDO_PATH . 'modules/options/class-tmdo-options-manager.php';
tests/unit/MigrationPhaseRemainingTest.php
+282
View File
@@ -0,0 +1,282 @@
<?php
declare(strict_types=1);
use PHPUnit\Framework\TestCase;
/**
* Unit tests for the 5 migration phases not covered in MigrationPhaseTest.php
* (P1-11): Diagnose, Install_Schema, Backfill_Bulk, Backfill_Unserialize,
* Verify_Sample.
*
* All engine dependencies (WPDO_Schema_Manager, WPDO_Migration_Orchestrator,
* WPDO_Entity_Migration_Engine, WPDO_Hook_Bus) use the real classes loaded via
* composer autoload. The $wpdb stub returns null/[] for all DB calls, giving
* zero-row results sufficient to exercise the logic paths under test.
*/
class MigrationPhaseRemainingTest extends TestCase {
/** @var object Original $wpdb saved for restoration. */
private object $original_wpdb;
protected function setUp(): void {
global $wpdb;
$this->original_wpdb = $wpdb;
$GLOBALS['_wp_options'] = array();
WPDO_Mode_Manager::reset_cache();
// Provide a fresh $wpdb with all methods the phases under test require,
// regardless of which prior test may have left a broken stub.
$wpdb = new class {
public string $prefix = 'wp_';
public string $users = 'wp_users';
public string $usermeta = 'wp_usermeta';
public string $postmeta = 'wp_postmeta';
public string $options = 'wp_options';
public string $last_error = '';
public array $queries = [];
public function prepare( string $sql, ...$args ): string {
$i = 0;
return preg_replace_callback( '/%[sd]/', function () use ( &$i, $args ) {
return (string) ( $args[ $i++ ] ?? '?' );
}, $sql );
}
public function get_var( string $sql ): ?string { return null; }
public function get_col( string $sql ): array { return []; }
public function get_results( string $sql, $output = null ): array { return []; }
public function query( string $sql ): int|bool { $this->queries[] = $sql; return 1; }
public function insert( string $t, array $d, $f = null ): int|false { return 1; }
public function get_charset_collate(): string { return ''; }
};
// Reset Schema_Manager request-scoped cache so table_exists() hits $wpdb each test.
$ref = new ReflectionClass( WPDO_Schema_Manager::class );
$prop = $ref->getProperty( 'table_exists_cache' );
$prop->setAccessible( true );
$prop->setValue( null, array() );
// The unit bootstrap loads Member_Fields / Post_Fields, which register entity
// groups at include time. These phases assert "no groups registered" behaviour,
// so clear the registry to isolate them from that ambient state.
$reg = new ReflectionClass( WPDO_Entity_Registry::class );
foreach ( array( 'groups', 'field_index' ) as $name ) {
$p = $reg->getProperty( $name );
$p->setAccessible( true );
$p->setValue( null, array() );
}
// Install_Schema re-fires wpdo_register_entity_fields, which would re-populate
// the registry from those same listeners — drop them for the duration.
$this->saved_field_listeners = $GLOBALS['_wp_filter_callbacks']['wpdo_register_entity_fields'] ?? array();
$GLOBALS['_wp_filter_callbacks']['wpdo_register_entity_fields'] = array();
WPDO_Entity_Registry::clear_pending_schemas();
}
/**
* Listeners removed in setUp() and restored in tearDown().
*
* @var array
*/
private array $saved_field_listeners = array();
protected function tearDown(): void {
global $wpdb;
$wpdb = $this->original_wpdb;
$GLOBALS['_wp_filter_callbacks']['wpdo_register_entity_fields'] = $this->saved_field_listeners;
}
private function make_job(): array {
return array(
'job_id' => 'test-job',
'log' => array(),
'state' => 'running',
'overall_progress' => 0,
'metrics' => array(
'ratio_start' => 1.5,
'ratio_now' => 1.5,
),
'options' => array(),
);
}
// ── WPDO_Phase_Diagnose ───────────────────────────────────────────────────
public function test_diagnose_name(): void {
$phase = new WPDO_Phase_Diagnose( 'user' );
$this->assertSame( 'diagnose', $phase->name() );
}
public function test_diagnose_returns_ok(): void {
$phase = new WPDO_Phase_Diagnose( 'user' );
$job = $this->make_job();
$result = $phase->execute( $job );
$this->assertSame( 'ok', $result['status'] );
}
public function test_diagnose_records_eav_rows_in_metrics(): void {
// With $wpdb returning null, count_eav_residue() → 0. Key must exist.
$phase = new WPDO_Phase_Diagnose( 'user' );
$job = $this->make_job();
$phase->execute( $job );
$this->assertArrayHasKey( 'eav_rows_now', $job['metrics'] );
$this->assertIsInt( $job['metrics']['eav_rows_now'] );
}
public function test_diagnose_records_ratio_in_metrics(): void {
// 0 users → ratio = 0. Key must exist.
$phase = new WPDO_Phase_Diagnose( 'user' );
$job = $this->make_job();
$phase->execute( $job );
$this->assertArrayHasKey( 'ratio_now', $job['metrics'] );
}
public function test_diagnose_appends_log_entry(): void {
$phase = new WPDO_Phase_Diagnose( 'user' );
$job = $this->make_job();
$phase->execute( $job );
$this->assertNotEmpty( $job['log'] );
$this->assertStringContainsString( 'Diagnose', $job['log'][0] );
}
// ── WPDO_Phase_Install_Schema ─────────────────────────────────────────────
public function test_install_schema_name(): void {
$phase = new WPDO_Phase_Install_Schema( 'user' );
$this->assertSame( 'install_schema', $phase->name() );
}
public function test_install_schema_succeeds_when_no_groups_registered(): void {
// No groups registered for 'user' in unit-test bootstrap → $missing stays empty.
$phase = new WPDO_Phase_Install_Schema( 'user' );
$job = $this->make_job();
$result = $phase->execute( $job );
$this->assertSame( 'ok', $result['status'] );
}
public function test_install_schema_appends_log_entry(): void {
$phase = new WPDO_Phase_Install_Schema( 'user' );
$job = $this->make_job();
$phase->execute( $job );
$this->assertNotEmpty( $job['log'] );
$this->assertStringContainsString( 'Schema migration ok', $job['log'][0] );
}
// ── WPDO_Phase_Backfill_Bulk ──────────────────────────────────────────────
public function test_backfill_bulk_name(): void {
$phase = new WPDO_Phase_Backfill_Bulk( 'user' );
$this->assertSame( 'backfill_bulk', $phase->name() );
}
public function test_backfill_bulk_skips_on_dry_run(): void {
$phase = new WPDO_Phase_Backfill_Bulk( 'user' );
$job = array_merge( $this->make_job(), array( 'options' => array( 'dry_run' => true ) ) );
$result = $phase->execute( $job );
$this->assertSame( 'ok', $result['status'] );
$this->assertStringContainsString( 'dry_run', $job['log'][0] ?? '' );
}
public function test_backfill_bulk_returns_ok_with_no_groups(): void {
// No groups → loop body never executes → 0 groups, 0 rows.
$phase = new WPDO_Phase_Backfill_Bulk( 'user' );
$job = $this->make_job();
$result = $phase->execute( $job );
$this->assertSame( 'ok', $result['status'] );
$found_summary = false;
foreach ( $job['log'] as $line ) {
if ( str_contains( $line, 'Bulk backfill' ) ) {
$found_summary = true;
$this->assertStringContainsString( '0 groups', $line );
break;
}
}
$this->assertTrue( $found_summary, 'Log must contain Bulk backfill summary.' );
}
// ── WPDO_Phase_Backfill_Unserialize ───────────────────────────────────────
public function test_backfill_unserialize_name(): void {
$phase = new WPDO_Phase_Backfill_Unserialize( 'user' );
$this->assertSame( 'backfill_unserialize', $phase->name() );
}
public function test_backfill_unserialize_skips_on_dry_run(): void {
$phase = new WPDO_Phase_Backfill_Unserialize( 'user' );
$job = array_merge( $this->make_job(), array( 'options' => array( 'dry_run' => true ) ) );
$result = $phase->execute( $job );
$this->assertSame( 'ok', $result['status'] );
$this->assertStringContainsString( 'dry_run', $job['log'][0] ?? '' );
}
public function test_backfill_unserialize_returns_ok_with_no_json_groups(): void {
// No groups with JSON fields → loop body never executes.
$phase = new WPDO_Phase_Backfill_Unserialize( 'user' );
$job = $this->make_job();
$result = $phase->execute( $job );
$this->assertSame( 'ok', $result['status'] );
}
public function test_backfill_unserialize_appends_total_log_entry(): void {
$phase = new WPDO_Phase_Backfill_Unserialize( 'user' );
$job = $this->make_job();
$phase->execute( $job );
$this->assertNotEmpty( $job['log'] );
$last = end( $job['log'] );
$this->assertStringContainsString( 'Row-by-row backfill', $last );
}
// ── WPDO_Phase_Verify_Sample ──────────────────────────────────────────────
public function test_verify_sample_name(): void {
$phase = new WPDO_Phase_Verify_Sample( 'user' );
$this->assertSame( 'verify_sample', $phase->name() );
}
public function test_verify_sample_24h_starts_window_when_no_started_at(): void {
$phase = new WPDO_Phase_Verify_Sample( 'user' );
$job = array_merge( $this->make_job(), array( 'options' => array( 'verify_24h' => true ) ) );
$result = $phase->execute( $job );
$this->assertSame( 'in_progress', $result['status'] );
$this->assertArrayHasKey( 'phase_started_at', $job );
}
public function test_verify_sample_24h_stays_in_progress_during_window(): void {
$phase = new WPDO_Phase_Verify_Sample( 'user' );
$job = array_merge(
$this->make_job(),
array(
'options' => array( 'verify_24h' => true ),
'phase_started_at' => time() - 3600, // 1 hour ago — still within 24h window
)
);
$result = $phase->execute( $job );
$this->assertSame( 'in_progress', $result['status'] );
}
public function test_verify_sample_succeeds_with_zero_users(): void {
// $wpdb->get_var() returns null → 0 users → 0 samples → 0 diffs → ok.
$phase = new WPDO_Phase_Verify_Sample( 'user' );
$job = $this->make_job();
$result = $phase->execute( $job );
$this->assertSame( 'ok', $result['status'] );
}
public function test_verify_sample_log_contains_compare_summary(): void {
$phase = new WPDO_Phase_Verify_Sample( 'user' );
$job = $this->make_job();
$phase->execute( $job );
$found = false;
foreach ( $job['log'] as $line ) {
if ( str_contains( $line, 'Verify' ) ) {
$found = true;
break;
}
}
$this->assertTrue( $found, 'Log must contain Verify summary.' );
}
public function test_verify_sample_constants(): void {
$this->assertSame( 500, WPDO_Phase_Verify_Sample::VERIFY_SAMPLE_MIN );
$this->assertEqualsWithDelta( 0.10, WPDO_Phase_Verify_Sample::VERIFY_SAMPLE_RATIO, 0.0001 );
}
}
tests/unit/MigrationPhaseTest.php
+272
View File
@@ -0,0 +1,272 @@
<?php
declare(strict_types=1);
use PHPUnit\Framework\TestCase;
/**
* Unit tests for WPDO_Migration_Phase_Base and WPDO_Phase_Completed.
*
* WPDO_Phase_Completed is the simplest phase — no external class calls — so it
* exercises the full interface contract without mocking infrastructure.
*/
class MigrationPhaseTest extends TestCase {
private function make_job( float $ratio_start = 1.5, float $ratio_now = 0.8 ): array {
return array(
'job_id' => 'test-job',
'log' => array(),
'state' => 'running',
'overall_progress' => 0,
'metrics' => array(
'ratio_start' => $ratio_start,
'ratio_now' => $ratio_now,
),
);
}
// ── WPDO_Phase_Completed ──────────────────────────────────────────────────
public function test_completed_returns_done_status(): void {
$phase = new WPDO_Phase_Completed( 'user' );
$job = $this->make_job();
$result = $phase->execute( $job );
$this->assertSame( 'done', $result['status'] );
}
public function test_completed_sets_state_to_completed(): void {
$phase = new WPDO_Phase_Completed( 'user' );
$job = $this->make_job();
$phase->execute( $job );
$this->assertSame( 'completed', $job['state'] );
}
public function test_completed_sets_overall_progress_to_100(): void {
$phase = new WPDO_Phase_Completed( 'user' );
$job = $this->make_job();
$phase->execute( $job );
$this->assertSame( 100, $job['overall_progress'] );
}
public function test_completed_sets_completed_at_timestamp(): void {
$before = time();
$phase = new WPDO_Phase_Completed( 'user' );
$job = $this->make_job();
$phase->execute( $job );
$this->assertGreaterThanOrEqual( $before, $job['completed_at'] );
$this->assertLessThanOrEqual( time(), $job['completed_at'] );
}
public function test_completed_appends_log_entry(): void {
$phase = new WPDO_Phase_Completed( 'user' );
$job = $this->make_job( 1.5, 0.75 );
$phase->execute( $job );
$this->assertNotEmpty( $job['log'] );
$last_line = end( $job['log'] );
$this->assertStringContainsString( 'Migration complete', $last_line );
}
public function test_completed_name_is_completed(): void {
$phase = new WPDO_Phase_Completed( 'user' );
$this->assertSame( 'completed', $phase->name() );
}
// ── WPDO_Migration_Phase_Base log truncation ──────────────────────────────
public function test_log_truncates_at_max_log_lines(): void {
$phase = new WPDO_Phase_Completed( 'user' );
$job = $this->make_job();
// Each execute() appends exactly one log entry — call it MAX+5 times.
$max = WPDO_Migration_Phase_Base::MAX_LOG_LINES;
for ( $i = 0; $i < $max + 5; $i++ ) {
$phase->execute( $job );
}
$this->assertCount( $max, $job['log'] );
}
public function test_log_keeps_most_recent_lines_when_truncating(): void {
$phase = new WPDO_Phase_Completed( 'user' );
$job = $this->make_job();
$max = WPDO_Migration_Phase_Base::MAX_LOG_LINES;
for ( $i = 0; $i < $max + 10; $i++ ) {
$phase->execute( $job );
}
// Log contains exactly MAX lines with truncation keeping the most recent.
$this->assertCount( $max, $job['log'] );
// First kept line was written after at least 10 entries were discarded.
$first_line = $job['log'][0];
$this->assertStringContainsString( 'Migration complete', $first_line );
}
// ── Phase interface contract ───────────────────────────────────────────────
public function test_phase_implements_interface(): void {
$phase = new WPDO_Phase_Completed( 'user' );
// Interfaces cannot be class_alias()'d; the phase contract is core-internal
// (only the 11 built-in phases implement it), so assert the canonical name.
$this->assertInstanceOf( TMDO_Migration_Phase_Interface::class, $phase );
}
public function test_phase_entity_type_injectable(): void {
$phase_user = new WPDO_Phase_Completed( 'user' );
$phase_term = new WPDO_Phase_Completed( 'term' );
// Both are independent instances — no shared state.
$job_a = $this->make_job();
$job_b = $this->make_job();
$phase_user->execute( $job_a );
$phase_term->execute( $job_b );
$this->assertSame( 'completed', $job_a['state'] );
$this->assertSame( 'completed', $job_b['state'] );
}
// ── Phase_Cleanup — RuntimeException guards (P1-11, highest priority) ────────
protected function setUp(): void {
$GLOBALS['_wp_options'] = [];
WPDO_Mode_Manager::reset_cache();
}
private function make_mode_option( string $entity_type, string $mode ): void {
$GLOBALS['_wp_options']['wpdo_bridge_modes'] = array( $entity_type => $mode );
WPDO_Mode_Manager::reset_cache();
}
public function test_cleanup_throws_when_mode_not_aeav_only(): void {
$this->make_mode_option( 'user', 'dual_write' );
$phase = new WPDO_Phase_Cleanup( 'user' );
$job = $this->make_job();
$this->expectException( \RuntimeException::class );
$this->expectExceptionMessageMatches( '/must be aeav_only/' );
$phase->execute( $job );
}
public function test_cleanup_throws_when_auto_backup_requested_but_no_path(): void {
$this->make_mode_option( 'user', 'aeav_only' );
$phase = new WPDO_Phase_Cleanup( 'user' );
$job = array_merge(
$this->make_job(),
array(
'options' => array( 'auto_backup' => true ),
'backup_path' => '', // empty — simulates backup that never ran
)
);
$this->expectException( \RuntimeException::class );
$this->expectExceptionMessageMatches( '/no backup_path on record/' );
$phase->execute( $job );
}
public function test_cleanup_skips_when_dry_run(): void {
$this->make_mode_option( 'user', 'dual_write' ); // wrong mode, but dry_run should short-circuit first
$phase = new WPDO_Phase_Cleanup( 'user' );
$job = array_merge( $this->make_job(), array( 'options' => array( 'dry_run' => true ) ) );
$result = $phase->execute( $job );
$this->assertSame( 'ok', $result['status'] );
$this->assertStringContainsString( 'dry_run', $job['log'][0] ?? '' );
}
// ── Phase_Demote ──────────────────────────────────────────────────────────────
public function test_demote_skips_when_not_aeav_only(): void {
$this->make_mode_option( 'user', 'shadow_read' );
$phase = new WPDO_Phase_Demote( 'user' );
$job = $this->make_job();
$result = $phase->execute( $job );
$this->assertSame( 'ok', $result['status'] );
$this->assertStringContainsString( 'skipped', $job['log'][0] ?? '' );
}
public function test_demote_transitions_aeav_only_to_dual_write(): void {
$this->make_mode_option( 'user', 'aeav_only' );
$phase = new WPDO_Phase_Demote( 'user' );
$job = $this->make_job();
$result = $phase->execute( $job );
$this->assertSame( 'ok', $result['status'] );
$this->assertSame( 'dual_write', WPDO_Mode_Manager::get( 'user' ) );
}
// ── Phase_Backup — skip when auto_backup=false ────────────────────────────────
public function test_backup_skips_when_auto_backup_false(): void {
$phase = new WPDO_Phase_Backup( 'user' );
$job = array_merge( $this->make_job(), array( 'options' => array( 'auto_backup' => false ) ) );
$result = $phase->execute( $job );
$this->assertSame( 'ok', $result['status'] );
$this->assertStringContainsString( 'skipped', $job['log'][0] ?? '' );
}
// ── Phase_Promote_Aeav ────────────────────────────────────────────────────────
public function test_promote_aeav_skips_when_already_aeav_only(): void {
$this->make_mode_option( 'user', 'aeav_only' );
$phase = new WPDO_Phase_Promote_Aeav( 'user' );
$job = $this->make_job();
$result = $phase->execute( $job );
$this->assertSame( 'ok', $result['status'] );
$this->assertStringContainsString( 'Already', $job['log'][0] ?? '' );
}
public function test_promote_aeav_transitions_from_shadow_read(): void {
$this->make_mode_option( 'user', 'shadow_read' );
$phase = new WPDO_Phase_Promote_Aeav( 'user' );
$job = $this->make_job();
$result = $phase->execute( $job );
$this->assertSame( 'ok', $result['status'] );
$this->assertSame( 'aeav_only', WPDO_Mode_Manager::get( 'user' ) );
}
// ── Phase_Promote_Shadow ──────────────────────────────────────────────────────
public function test_promote_shadow_transitions_from_dual_write(): void {
$this->make_mode_option( 'user', 'dual_write' );
$phase = new WPDO_Phase_Promote_Shadow( 'user' );
$job = $this->make_job();
$result = $phase->execute( $job );
$this->assertSame( 'ok', $result['status'] );
$this->assertSame( 'shadow_read', WPDO_Mode_Manager::get( 'user' ) );
}
public function test_promote_shadow_skips_when_already_at_shadow_or_higher(): void {
$this->make_mode_option( 'user', 'aeav_only' );
$phase = new WPDO_Phase_Promote_Shadow( 'user' );
$job = $this->make_job();
$result = $phase->execute( $job );
$this->assertSame( 'ok', $result['status'] );
// Mode should be unchanged (already past shadow_read).
$this->assertSame( 'aeav_only', WPDO_Mode_Manager::get( 'user' ) );
}
// ── Phase name() contract ─────────────────────────────────────────────────────
public function test_all_phases_return_expected_names(): void {
$cases = array(
array( new WPDO_Phase_Backup( 'user' ), 'backup' ),
array( new WPDO_Phase_Cleanup( 'user' ), 'cleanup' ),
array( new WPDO_Phase_Demote( 'user' ), 'demote' ),
array( new WPDO_Phase_Promote_Aeav( 'user' ), 'promote_aeav' ),
array( new WPDO_Phase_Promote_Shadow( 'user' ), 'promote_shadow' ),
);
foreach ( $cases as [ $phase, $expected ] ) {
$this->assertSame( $expected, $phase->name() );
}
}
}