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

fix(2meet-data-optimizer): report entity group name collisions instead of silently dropping

Browse Source 
- register_group() keeps the first definition but records a field diff (added/removed/changed) when the same entity/group is re-registered differently; identical re-registration stays silent
- Surface collisions via Site Health (wpdo_entity_group_collisions), the admin Doctor tab, and wp wpdo doctor; warning log throttled to once a day
- Verify: EntityRegistryCollisionTest (7); core unit 613 / integration 432, HP 141/49, WC 10/22 OK
- PR: PR-017
This commit is contained in:
wpdev
2026-09-25 23:27:05 +08:00
parent 07db7734cf
commit e9d8696c93
6 changed files with 248 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files
admin/class-tmdo-admin.php
+2 -1
View File
@@ -2990,7 +2990,7 @@ wpdo.getListings({ per_page: 3 }).then(r => console.log(r));'
?>
<h2><?php esc_html_e( '健康檢查（Doctor）', '2meet-data-optimizer' ); ?></h2>
<p class="description">
<?php esc_html_e( '7 項自我診斷檢查：schema 完整性、錯誤預算、hook 衝突、autoload 大小、postmeta 爆量、orphan zone rows、缺少快照。', '2meet-data-optimizer' ); ?>
<?php esc_html_e( '8 項自我診斷檢查：schema 完整性、錯誤預算、hook 衝突、autoload 大小、postmeta 爆量、orphan zone rows、缺少快照、實體群組名稱衝突。', '2meet-data-optimizer' ); ?>
</p>
<p>
<a class="button" href="<?php echo esc_url( admin_url( 'site-health.php' ) ); ?>">
@@ -3011,6 +3011,7 @@ wpdo.getListings({ per_page: 3 }).then(r => console.log(r));'
'wpdo_postmeta_explosion' => array( 'check_postmeta_explosion', __( 'wp_postmeta 爆量', '2meet-data-optimizer' ) ),
'wpdo_orphan_zone_rows' => array( 'check_orphan_zone_rows', __( 'Orphan zone rows', '2meet-data-optimizer' ) ),
'wpdo_missing_snapshot' => array( 'check_missing_snapshot', __( '缺少最近快照', '2meet-data-optimizer' ) ),
'wpdo_entity_group_collisions' => array( 'check_entity_group_collisions', __( '實體群組名稱衝突', '2meet-data-optimizer' ) ),
);
?>
<table class="widefat striped">
admin/class-tmdo-help-tabs.php
+2 -1
View File
@@ -184,7 +184,7 @@ class TMDO_Help_Tabs {
* @return string
*/
private static function content_doctor(): string {
return '<p>' . esc_html__( '7 項自動健康檢查：', '2meet-data-optimizer' ) . '</p>'
return '<p>' . esc_html__( '8 項自動健康檢查：', '2meet-data-optimizer' ) . '</p>'
. '<ol class="wpdo-list-disc">'
. '<li><strong>schema_drift</strong> — ' . esc_html__( '所有 v2 表是否存在', '2meet-data-optimizer' ) . '</li>'
. '<li><strong>error_budget</strong> — ' . esc_html__( '7 天內 wp_wpdo_errors 行數', '2meet-data-optimizer' ) . '</li>'
@@ -193,6 +193,7 @@ class TMDO_Help_Tabs {
. '<li><strong>postmeta_explosion</strong> — ' . esc_html__( 'wp_postmeta > 5M 行', '2meet-data-optimizer' ) . '</li>'
. '<li><strong>orphan_zone_rows</strong> — ' . esc_html__( '已 idle 的 module 但 zone 表還有資料', '2meet-data-optimizer' ) . '</li>'
. '<li><strong>missing_snapshot</strong> — ' . esc_html__( '在 cutover/cleanup/complete 但 7 天沒 snapshot', '2meet-data-optimizer' ) . '</li>'
. '<li><strong>entity_group_collisions</strong> — ' . esc_html__( '同名實體群組被不同外掛以不同欄位註冊（後者被忽略）', '2meet-data-optimizer' ) . '</li>'
. '</ol>'
. '<p>' . esc_html__( '結果有 5 分鐘 transient cache，剛操作完想立刻看新值請等下個週期。', '2meet-data-optimizer' ) . '</p>';
}
cli/class-tmdo-cli.php
+19
View File
@@ -330,6 +330,25 @@ class TMDO_CLI {
WP_CLI::log( ' [OK] Crypto key derivable (AUTH_KEY / SECURE_AUTH_SALT present)' );
}
// ── Entity group name collisions ─────────────────────────────────────────
$collisions = TMDO_Entity_Registry::get_collisions();
if ( empty( $collisions ) ) {
WP_CLI::log( ' [OK] No entity group name collisions' );
}
foreach ( $collisions as $c ) {
WP_CLI::warning(
sprintf(
' [COLLISION] %s/%s registered twice with different fields (second ignored) — added: %s; removed: %s; changed: %s',
$c['entity_type'],
$c['group'],
implode( ', ', $c['added'] ) ?: '-',
implode( ', ', $c['removed'] ) ?: '-',
implode( ', ', $c['changed'] ) ?: '-'
)
);
$all_ok = false;
}
// Check recent errors.
$errors = TMDO_Logger::get_recent( '', 5 );
if ( ! empty( $errors ) ) {
includes/diagnostic/class-tmdo-site-health.php
+45 -2
View File
@@ -2,7 +2,7 @@
/**
* TMDO_Site_Health — WordPress Site Health integration (v2.2.0 M3).
*
* Registers 7 tests under Tools → Site Health → Status:
* Registers 8 tests under Tools → Site Health → Status:
* 1. wpdo_schema_drift (critical)
* 2. wpdo_error_budget (recommended)
* 3. wpdo_hook_conflicts (recommended)
@@ -10,6 +10,7 @@
* 5. wpdo_postmeta_explosion (recommended)
* 6. wpdo_orphan_zone_rows (recommended)
* 7. wpdo_missing_snapshot (critical)
* 8. wpdo_entity_group_collisions (recommended)
*
* Each test result is cached for 5 minutes to keep Site Health responsive.
*
@@ -41,6 +42,7 @@ class TMDO_Site_Health {
'wpdo_postmeta_explosion' => 'check_postmeta_explosion',
'wpdo_orphan_zone_rows' => 'check_orphan_zone_rows',
'wpdo_missing_snapshot' => 'check_missing_snapshot',
'wpdo_entity_group_collisions' => 'check_entity_group_collisions',
);
/**
@@ -53,7 +55,7 @@ class TMDO_Site_Health {
}
/**
* Register the 7 tests with WP Site Health.
* Register the 8 tests with WP Site Health.
*
* @param array $tests Existing tests.
* @return array
@@ -83,6 +85,7 @@ class TMDO_Site_Health {
'wpdo_postmeta_explosion' => __( 'WPDO postmeta explosion', '2meet-data-optimizer' ),
'wpdo_orphan_zone_rows' => __( 'WPDO orphan zone rows', '2meet-data-optimizer' ),
'wpdo_missing_snapshot' => __( 'WPDO missing snapshot', '2meet-data-optimizer' ),
'wpdo_entity_group_collisions' => __( 'WPDO entity group collisions', '2meet-data-optimizer' ),
);
return $map[ $key ] ?? $key;
}
@@ -425,6 +428,46 @@ class TMDO_Site_Health {
// ─── helpers ──────────────────────────────────────────────────────────
// ─── Test 8: Entity group name collisions ───────────────────────────
/**
* Report entity groups registered twice with different definitions.
*
* Not cached: the collision list is in-memory state rebuilt on every
* request, so reading it is free and a transient would only go stale.
*
* @return array Site Health result.
*/
public static function check_entity_group_collisions(): array {
$collisions = class_exists( 'TMDO_Entity_Registry' ) ? TMDO_Entity_Registry::get_collisions() : array();
if ( empty( $collisions ) ) {
return self::wrap( 'wpdo_entity_group_collisions', self::pass( __( 'No entity group name collisions.', '2meet-data-optimizer' ) ) );
}
$lines = array();
foreach ( $collisions as $c ) {
$lines[] = sprintf(
'%s/%s (+%s −%s ~%s)',
$c['entity_type'],
$c['group'],
implode( ',', $c['added'] ) ?: '-',
implode( ',', $c['removed'] ) ?: '-',
implode( ',', $c['changed'] ) ?: '-'
);
}
return self::wrap(
'wpdo_entity_group_collisions',
self::fail(
__( 'WPDO entity group name collisions', '2meet-data-optimizer' ),
sprintf(
/* translators: %s: list of entity/group names with field differences */
__( 'Another plugin registered these groups with a different field list; its definition was ignored and the first one kept: %s', '2meet-data-optimizer' ),
implode( '; ', $lines )
),
'recommended'
)
);
}
/**
* Wrap a raw check result with required Site Health envelope fields.
*
includes/engine/class-tmdo-entity-registry.php
+62 -8
View File
@@ -31,6 +31,9 @@ final class TMDO_Entity_Registry {
/** @var array<int, array{type:string, group:string, fields:array}> 待建表的 Schema 清單 */
private static array $pending_schemas = array();
/** @var array<string, array> "entity/group" → 同名群組以不同定義重複註冊的紀錄 */
private static array $collisions = array();
/** 合法的欄位型別 */
public const VALID_TYPES = array(
'text',
@@ -54,6 +57,7 @@ final class TMDO_Entity_Registry {
self::$groups = array();
self::$field_index = array();
self::$pending_schemas = array();
self::$collisions = array();
}
// ─────────────────────────────────────────────────────────
@@ -105,11 +109,6 @@ final class TMDO_Entity_Registry {
return false;
}
// 防重複登錄
if ( isset( self::$groups[ $entity_type ][ $group_name ] ) ) {
return false;
}
// 驗證並正規化欄位定義
$normalized = array();
@@ -141,15 +140,25 @@ final class TMDO_Entity_Registry {
$normalized_field['entity_type'] = $entity_type;
$normalized[] = $normalized_field;
// 建立索引以供快速查詢
self::$field_index[ $entity_type ][ $normalized_field['key'] ] = $normalized_field;
}
if ( empty( $normalized ) ) {
return false;
}
// 防重複登錄：相同定義（init:1 重新觸發）靜默略過；定義不同則記錄衝突，保留先註冊者。
if ( isset( self::$groups[ $entity_type ][ $group_name ] ) ) {
if ( self::$groups[ $entity_type ][ $group_name ] !== $normalized ) {
self::record_collision( $entity_type, $group_name, self::$groups[ $entity_type ][ $group_name ], $normalized );
}
return false;
}
// 建立索引以供快速查詢
foreach ( $normalized as $normalized_field ) {
self::$field_index[ $entity_type ][ $normalized_field['key'] ] = $normalized_field;
}
self::$groups[ $entity_type ][ $group_name ] = $normalized;
// 加入待建表佇列
@@ -162,6 +171,51 @@ final class TMDO_Entity_Registry {
return true;
}
/**
* 記錄同名群組衝突（每個 entity/group 每請求一筆），並寫入 warning。
*
* 註冊每個請求都會跑，warning 以 transient 節流為每天一次，避免灌爆 wpdo_errors。
*/
private static function record_collision( string $entity_type, string $group_name, array $existing, array $incoming ): void {
$id = $entity_type . '/' . $group_name;
if ( isset( self::$collisions[ $id ] ) ) {
return;
}
$old = array_column( $existing, null, 'key' );
$new = array_column( $incoming, null, 'key' );
$changed = array();
foreach ( array_intersect_key( $new, $old ) as $key => $field ) {
if ( $field !== $old[ $key ] ) {
$changed[] = (string) $key;
}
}
self::$collisions[ $id ] = array(
'entity_type' => $entity_type,
'group' => $group_name,
'added' => array_map( 'strval', array_keys( array_diff_key( $new, $old ) ) ),
'removed' => array_map( 'strval', array_keys( array_diff_key( $old, $new ) ) ),
'changed' => $changed,
);
$throttle = 'tmdo_group_collision_' . md5( (string) wp_json_encode( self::$collisions[ $id ] ) );
if ( class_exists( 'TMDO_Logger' ) && false === get_transient( $throttle ) ) {
set_transient( $throttle, 1, DAY_IN_SECONDS );
TMDO_Logger::warning( 'entity_group_collision', self::$collisions[ $id ] );
}
}
/**
* 本請求偵測到的同名群組衝突（第二份定義已被捨棄）。
*
* @return array<int, array{entity_type:string, group:string, added:string[], removed:string[], changed:string[]}>
*/
public static function get_collisions(): array {
return array_values( self::$collisions );
}
// ─────────────────────────────────────────────────────────
// 查詢 API
// ─────────────────────────────────────────────────────────
tests/unit/EntityRegistryCollisionTest.php
+97
View File
@@ -0,0 +1,97 @@
<?php
declare(strict_types=1);
use PHPUnit\Framework\TestCase;
/**
* Entity group name collisions.
*
* Two providers registering the same entity/group name used to have the
* second definition dropped with no trace. Identical re-registration (core
* re-fires the registration hooks on init:1) stays silent; a different
* definition is recorded with a field diff and surfaced in Site Health.
*/
class EntityRegistryCollisionTest extends TestCase {
protected function setUp(): void {
if ( ! class_exists( 'TMDO_Site_Health' ) ) {
require_once TMDO_PATH . 'includes/diagnostic/class-tmdo-site-health.php';
}
TMDO_Entity_Registry::init();
TMDO_Entity_Registry::register_adapter( 'post', $this->createMock( TMDO_Entity_Adapter_Interface::class ) );
$GLOBALS['_wp_options'] = array();
}
private function first_definition(): array {
return array(
array( 'key' => 'hp_price', 'type' => 'decimal', 'searchable' => true ),
array( 'key' => 'hp_featured', 'type' => 'boolean' ),
);
}
public function test_identical_reregistration_is_silent(): void {
$this->assertTrue( TMDO_Entity_Registry::register_group( 'post', 'hp_listing_core', $this->first_definition() ) );
$this->assertFalse( TMDO_Entity_Registry::register_group( 'post', 'hp_listing_core', $this->first_definition() ) );
$this->assertSame( array(), TMDO_Entity_Registry::get_collisions() );
}
public function test_different_definition_is_recorded_with_field_diff(): void {
TMDO_Entity_Registry::register_group( 'post', 'hp_listing_core', $this->first_definition() );
$second = array(
array( 'key' => 'hp_price', 'type' => 'integer', 'searchable' => true ),
array( 'key' => 'hp_vendor', 'type' => 'integer' ),
);
$this->assertFalse( TMDO_Entity_Registry::register_group( 'post', 'hp_listing_core', $second ) );
$collisions = TMDO_Entity_Registry::get_collisions();
$this->assertCount( 1, $collisions );
$this->assertSame( 'post', $collisions[0]['entity_type'] );
$this->assertSame( 'hp_listing_core', $collisions[0]['group'] );
$this->assertSame( array( 'hp_vendor' ), $collisions[0]['added'] );
$this->assertSame( array( 'hp_featured' ), $collisions[0]['removed'] );
$this->assertSame( array( 'hp_price' ), $collisions[0]['changed'] );
}
public function test_first_definition_wins(): void {
TMDO_Entity_Registry::register_group( 'post', 'hp_listing_core', $this->first_definition() );
TMDO_Entity_Registry::register_group( 'post', 'hp_listing_core', array( array( 'key' => 'hp_vendor', 'type' => 'integer' ) ) );
$this->assertSame( array( 'hp_price', 'hp_featured' ), TMDO_Entity_Registry::get_group_keys( 'post', 'hp_listing_core' ) );
$this->assertNull( TMDO_Entity_Registry::get_field( 'post', 'hp_vendor' ) );
}
public function test_same_collision_is_recorded_once_per_request(): void {
TMDO_Entity_Registry::register_group( 'post', 'g', $this->first_definition() );
$other = array( array( 'key' => 'x', 'type' => 'text' ) );
TMDO_Entity_Registry::register_group( 'post', 'g', $other );
TMDO_Entity_Registry::register_group( 'post', 'g', $other );
$this->assertCount( 1, TMDO_Entity_Registry::get_collisions() );
}
public function test_init_clears_collisions(): void {
TMDO_Entity_Registry::register_group( 'post', 'g', $this->first_definition() );
TMDO_Entity_Registry::register_group( 'post', 'g', array( array( 'key' => 'x', 'type' => 'text' ) ) );
TMDO_Entity_Registry::init();
$this->assertSame( array(), TMDO_Entity_Registry::get_collisions() );
}
public function test_site_health_reports_collisions(): void {
$this->assertSame( 'good', TMDO_Site_Health::check_entity_group_collisions()['status'] );
TMDO_Entity_Registry::register_group( 'post', 'hp_listing_core', $this->first_definition() );
TMDO_Entity_Registry::register_group( 'post', 'hp_listing_core', array( array( 'key' => 'x', 'type' => 'text' ) ) );
$result = TMDO_Site_Health::check_entity_group_collisions();
$this->assertSame( 'recommended', $result['status'] );
$this->assertStringContainsString( 'post/hp_listing_core', $result['description'] );
}
public function test_site_health_registers_the_collision_test(): void {
$tests = TMDO_Site_Health::register_tests( array() );
$this->assertArrayHasKey( 'wpdo_entity_group_collisions', $tests['direct'] );
}
}