chore: initial snapshot of 2meet-data-optimizer v0.1.0

Baseline before backporting wp-data-optimizer v3.0.1-v3.4.6.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TbG1keQQ7XBa7qMQY16KCY
This commit is contained in:
2026-07-31 05:06:36 +08:00
commit d36bb954d1
206 changed files with 66538 additions and 0 deletions
@@ -0,0 +1,195 @@
<?php
/**
* Base class for all WPDO interceptors.
*
* @package WP_Data_Optimizer
*/
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
/**
* Base class for all WPDO interceptors.
*
* Ported from HPCT_Interceptor_Base with WPDO enhancements:
* - Uses TMDO_Feature_Flags (7-state) instead of HPCT 4-state
* - Uses TMDO_Logger instead of HPCT_Logger
* - Adds zone awareness for future Zone-based interceptors
*/
abstract class TMDO_Interceptor_Base {
/**
* Module name — set in each subclass.
*
* @var string
*/
protected string $module = '';
/**
* Whether to send admin email on first error.
*
* @var bool
*/
protected bool $email_on_error = true;
/**
* Return true when the module is fully enabled (reads from custom table).
*
* @return bool True if module is in complete state.
*/
protected function is_enabled(): bool {
return TMDO_Feature_Flags::is_complete( $this->module );
}
/**
* Return true when dual-write is active (writes go to both native + custom).
*
* @return bool True if module is in a write-active state.
*/
protected function is_write_active(): bool {
return TMDO_Feature_Flags::is_write_active( $this->module );
}
/**
* Return true when the module should intercept reads or writes.
*
* @return bool True if module is enabled or write-active.
*/
protected function is_active(): bool {
return $this->is_enabled() || $this->is_write_active();
}
/**
* Execute a custom-table callable safely.
*
* If $custom throws, log and return $native_fallback().
* After 3 consecutive errors in a request, disable the module.
*
* @param callable $custom Custom table read/write callable.
* @param callable $native_fallback Original WordPress callable.
* @param string $hook Hook name for logging context.
* @return mixed
* @throws \RuntimeException When the custom callable returns a WP_Error.
*/
protected function intercept( callable $custom, callable $native_fallback, string $hook = '' ): mixed {
if ( ! $this->is_enabled() ) {
return $native_fallback();
}
try {
$result = $custom();
if ( is_wp_error( $result ) ) {
throw new \RuntimeException( $result->get_error_message() );
}
return $result;
} catch ( \Throwable $e ) {
$this->handle_error(
$hook ?: 'intercept',
$e->getMessage(),
array(
'exception' => get_class( $e ),
'file' => $e->getFile(),
'line' => $e->getLine(),
)
);
return $native_fallback();
}
}
/**
* Dual-write: call native first, then sync to custom table.
* Custom failure is non-fatal.
*
* @param callable $native Original write callable (always executed).
* @param callable $custom Custom table write callable.
* @param string $hook Hook name for logging.
* @return mixed Return value of $native.
*/
protected function dual_write( callable $native, callable $custom, string $hook = '' ): mixed {
$result = $native();
if ( $this->is_write_active() || $this->is_enabled() ) {
try {
$custom( $result );
} catch ( \Throwable $e ) {
$this->handle_error(
$hook ?: 'dual_write',
$e->getMessage(),
array(
'exception' => get_class( $e ),
)
);
}
}
return $result;
}
/**
* Register all hooks. Called by TMDO_Core.
*
* @return void
*/
abstract public function register_hooks(): void;
// ── Private helpers ───────────────────────────────────────────────────
/**
* Per-request consecutive error counter, keyed by module.
*
* @var array
*/
private static array $error_counts = array();
/**
* Handles an interceptor error and auto-disables the module after 3 consecutive errors.
*
* @param string $hook Hook name for logging context.
* @param string $message Error message.
* @param array $context Additional context data.
* @return void
*/
private function handle_error( string $hook, string $message, array $context = array() ): void {
TMDO_Logger::error( $this->module, $hook, $message, $context );
self::$error_counts[ $this->module ] = ( self::$error_counts[ $this->module ] ?? 0 ) + 1;
if ( self::$error_counts[ $this->module ] >= 3 ) {
TMDO_Feature_Flags::reset( $this->module );
TMDO_Logger::error( $this->module, $hook, 'Module auto-disabled after 3 consecutive errors.' );
if ( $this->email_on_error ) {
$this->notify_admin( $message );
$this->email_on_error = false;
}
}
}
/**
* Sends an admin notification email when a module is auto-disabled.
*
* @param string $message Error message to include in the notification.
* @return void
*/
private function notify_admin( string $message ): void {
$admin_email = get_option( 'admin_email' );
if ( ! $admin_email ) {
return;
}
wp_mail(
$admin_email,
sprintf( '[WPDO] Module "%s" auto-disabled', $this->module ),
sprintf(
"The WPDO module \"%s\" has been automatically disabled due to repeated errors.\n\nLast error: %s\n\nPlease review the error log at Tools > WP Data Optimizer > Logs.",
$this->module,
$message
)
);
}
}
@@ -0,0 +1,400 @@
<?php
/**
* Zone-aware dual-write dispatcher for WordPress metadata API.
*
* @package WP_Data_Optimizer
*/
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
/**
* Zone-aware dual-write dispatcher.
*
* Hooks into WordPress metadata API (add/update/delete_post_metadata)
* and routes writes to the appropriate zone handler based on Schema Registry.
*
* Read path: intercepts get_post_metadata and routes to the correct zone
* when the module is in a read-custom state.
*
* This bridge handles ONLY zone-registered fields (hot/warm/cold).
* Archive zone is not intercepted here — it is triggered by cron/manual sweep.
* HPCT-inherited modules have their own dedicated interceptors.
*/
class TMDO_Sync_Bridge {
/**
* Prevent recursion when we call native meta functions internally.
*
* @var bool
*/
private static bool $bypassing = false;
/**
* Request-level cache for Schema Registry field lookups (post_type:meta_key => field|false).
*
* @var array
*/
private static array $field_cache = array();
/**
* Register all metadata hooks.
*/
public function register_hooks(): void {
add_filter( 'get_post_metadata', array( $this, 'intercept_get' ), 10, 5 );
add_filter( 'update_post_metadata', array( $this, 'intercept_update' ), 10, 5 );
add_filter( 'add_post_metadata', array( $this, 'intercept_add' ), 10, 5 );
add_action( 'deleted_post_meta', array( $this, 'intercept_delete' ), 10, 4 );
add_action( 'before_delete_post', array( $this, 'cleanup_post' ), 10, 1 );
}
/**
* Intercept get_post_meta — read from zone table when module is in read-custom state.
*
* @param mixed $value Existing filtered value (null by default).
* @param int $post_id Post ID.
* @param string $meta_key Meta key (empty = get all).
* @param bool $single Whether to return single value.
* @param string $meta_type Meta type (always 'post').
* @return mixed
*/
public function intercept_get( $value, int $post_id, string $meta_key, bool $single, string $meta_type = 'post' ) { // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.FoundAfterLastUsed -- Required by get_post_metadata filter signature.
if ( self::$bypassing || empty( $meta_key ) || $post_id <= 0 ) {
return $value;
}
$post_type = get_post_type( $post_id );
if ( ! $post_type ) {
return $value;
}
$field = $this->get_field_cached( $post_type, $meta_key );
if ( ! $field ) {
return $value;
}
$module = $this->get_zone_module( $field['zone'], $post_type );
if ( ! TMDO_Feature_Flags::is_read_custom( $module ) ) {
return $value;
}
try {
$zone_value = $this->read_from_zone( $field, $post_id, $post_type, $meta_key );
if ( null === $zone_value ) {
return $value;
}
// phpcs:ignore Squiz.PHP.CommentedOutCode.Found -- This is an explanatory comment, not commented-out code.
// Wrap in array: WP unwraps $check[0] for $single=true, casts (array)$check for $single=false.
return array( $zone_value );
} catch ( \Throwable $e ) {
TMDO_Logger::error( $module, 'get_post_metadata', $e->getMessage() );
return $value;
}
}
/**
* Intercept update_post_meta — dual-write to zone table.
*
* @param null|bool $check Whether to short-circuit (null = proceed).
* @param int $post_id Post ID.
* @param string $meta_key Meta key.
* @param mixed $meta_value Meta value.
* @param mixed $prev_value Previous value.
* @return null|bool
*/
public function intercept_update( $check, int $post_id, string $meta_key, $meta_value, $prev_value ) { // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.FoundAfterLastUsed
if ( self::$bypassing || $post_id <= 0 ) {
return $check;
}
$post_type = get_post_type( $post_id );
if ( ! $post_type ) {
return $check;
}
// v2.9.2 Entity Bridge guard: when post mode is dual_write or higher
// AND the key is registered in the new Entity Registry, the unified
// Hook Bus is the source of truth — Sync_Bridge must not also write
// to the legacy zone table to avoid duplicate flat writes.
if ( self::is_owned_by_entity_bridge( $meta_key ) ) {
return $check;
}
$field = $this->get_field_cached( $post_type, $meta_key );
if ( ! $field ) {
return $check;
}
$module = $this->get_zone_module( $field['zone'], $post_type );
if ( ! TMDO_Feature_Flags::is_write_active( $module ) ) {
return $check;
}
// Write to zone table (non-fatal on failure).
try {
$this->write_to_zone( $field, $post_id, $post_type, $meta_key, $meta_value );
} catch ( \Throwable $e ) {
TMDO_Logger::error( $module, 'update_post_metadata', $e->getMessage() );
}
// Return null — let WordPress proceed with native postmeta write.
// In cleanup/complete states, we could skip native write, but for safety
// we always allow it during zone migration lifecycle.
return $check;
}
/**
* Whether the given post meta_key is now owned by the Entity Bridge,
* meaning Sync_Bridge should defer to the unified Hook Bus and skip its
* zone write to avoid duplicate flat writes.
*
* Returns true only when ALL of:
* - TMDO_Mode_Manager and TMDO_Entity_Registry classes exist
* - post mode is dual_write or higher (writes_to_flat returns true)
* - the key is registered for entity_type=post
*
* Default post mode is `disabled`, so this returns false in all
* environments that have not opted in to Entity Bridge — keeping the
* legacy Sync_Bridge → zone path unchanged.
*
* @param string $meta_key Meta key being written.
* @return bool
* @since 2.9.2
*/
private static function is_owned_by_entity_bridge( string $meta_key ): bool {
if ( ! class_exists( 'TMDO_Mode_Manager' ) || ! class_exists( 'TMDO_Entity_Registry' ) ) {
return false;
}
if ( ! TMDO_Mode_Manager::writes_to_flat( 'post' ) ) {
return false;
}
return null !== TMDO_Entity_Registry::get_field( 'post', $meta_key );
}
/**
* Intercept add_post_meta — dual-write to zone table.
*
* @param mixed $check Whether to short-circuit.
* @param int $post_id Post ID.
* @param string $meta_key Meta key.
* @param mixed $meta_value Meta value.
* @param mixed $unique Whether the meta key should be unique. Not used directly.
* @return mixed Filtered check value.
*/
public function intercept_add( $check, int $post_id, string $meta_key, $meta_value, $unique ) { // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.FoundAfterLastUsed -- Required by add_post_metadata filter signature.
if ( self::$bypassing || $post_id <= 0 ) {
return $check;
}
$post_type = get_post_type( $post_id );
if ( ! $post_type ) {
return $check;
}
// v2.9.2 Entity Bridge guard — see is_owned_by_entity_bridge() docblock.
if ( self::is_owned_by_entity_bridge( $meta_key ) ) {
return $check;
}
$field = $this->get_field_cached( $post_type, $meta_key );
if ( ! $field ) {
return $check;
}
$module = $this->get_zone_module( $field['zone'], $post_type );
if ( ! TMDO_Feature_Flags::is_write_active( $module ) ) {
return $check;
}
try {
$this->write_to_zone( $field, $post_id, $post_type, $meta_key, $meta_value );
} catch ( \Throwable $e ) {
TMDO_Logger::error( $module, 'add_post_metadata', $e->getMessage() );
}
return $check;
}
/**
* After a postmeta is deleted, remove from zone table too.
*
* Hooked to 'deleted_post_meta' (fires after native delete completes).
*
* @param int[] $meta_ids Array of deleted meta IDs.
* @param int $post_id Post ID.
* @param string $meta_key Meta key.
* @param mixed $meta_value Meta value. Not used directly.
* @return void
*/
public function intercept_delete( $meta_ids, int $post_id, string $meta_key, $meta_value ): void { // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.FoundAfterLastUsed -- Required by deleted_post_meta action signature.
if ( self::$bypassing || $post_id <= 0 ) {
return;
}
$post_type = get_post_type( $post_id );
if ( ! $post_type ) {
return;
}
$field = $this->get_field_cached( $post_type, $meta_key );
if ( ! $field ) {
return;
}
$module = $this->get_zone_module( $field['zone'], $post_type );
if ( ! TMDO_Feature_Flags::is_write_active( $module ) ) {
return;
}
try {
$this->delete_from_zone( $field, $post_id, $post_type, $meta_key );
} catch ( \Throwable $e ) {
TMDO_Logger::error( $module, 'deleted_post_meta', $e->getMessage() );
}
}
/**
* When a post is permanently deleted, clean up all zone data.
*
* @param int $post_id Post ID being deleted.
* @return void
*/
public function cleanup_post( int $post_id ): void {
$post_type = get_post_type( $post_id );
if ( ! $post_type ) {
return;
}
$registry = TMDO_Schema_Registry::instance();
// Clean Hot zone.
if ( ! empty( $registry->get_hot_columns( $post_type ) ) ) {
try {
TMDO_Zone_Hot::delete( $post_id, $post_type );
} catch ( \Throwable $e ) {
TMDO_Logger::error( 'hot_' . $post_type, 'before_delete_post', $e->getMessage() );
}
}
// Clean Cold zone.
if ( ! empty( $registry->get_cold_meta_keys( $post_type ) ) ) {
try {
TMDO_Zone_Cold::delete( $post_id, $post_type );
} catch ( \Throwable $e ) {
TMDO_Logger::error( 'cold_' . $post_type, 'before_delete_post', $e->getMessage() );
}
}
// Clean Warm zone.
try {
TMDO_Zone_Warm::delete_all( $post_id );
} catch ( \Throwable $e ) {
TMDO_Logger::error( 'warm', 'before_delete_post', $e->getMessage() );
}
// Clean Archive zone.
try {
TMDO_Zone_Archive::delete( $post_id );
} catch ( \Throwable $e ) {
TMDO_Logger::error( 'archive', 'before_delete_post', $e->getMessage() );
}
}
// ── Private helpers ───────────────────────────────────────────────────
/**
* Get a registered field with a request-level static cache.
*
* @param string $post_type Post type.
* @param string $meta_key Meta key.
* @return array|null Field definition, or null if not registered.
*/
private function get_field_cached( string $post_type, string $meta_key ): ?array {
$cache_key = $post_type . ':' . $meta_key;
if ( ! array_key_exists( $cache_key, self::$field_cache ) ) {
self::$field_cache[ $cache_key ] = TMDO_Schema_Registry::instance()->get_field( $post_type, $meta_key );
}
return self::$field_cache[ $cache_key ];
}
/**
* Derive module name from zone + post_type for feature flag lookups.
*
* @param string $zone Zone identifier (hot, cold, warm, archive).
* @param string $post_type Post type.
* @return string Module name.
*/
private function get_zone_module( string $zone, string $post_type ): string {
return match ( $zone ) {
'hot' => 'hot_' . sanitize_key( $post_type ),
'cold' => 'cold_' . sanitize_key( $post_type ),
'warm' => 'warm',
'archive' => 'archive',
default => 'unknown',
};
}
/**
* Read a value from the appropriate zone.
*
* @param array $field Field definition from Schema Registry.
* @param int $post_id Post ID.
* @param string $post_type Post type.
* @param string $meta_key Meta key.
* @return mixed Value from zone or null.
*/
private function read_from_zone( array $field, int $post_id, string $post_type, string $meta_key ): mixed {
return match ( $field['zone'] ) {
'hot' => TMDO_Zone_Hot::get( $post_id, $post_type, $field['column'] ),
'cold' => TMDO_Zone_Cold::get( $post_id, $post_type, $meta_key ),
'warm' => TMDO_Zone_Warm::get( $post_id, $meta_key ),
default => null,
};
}
/**
* Write a value to the appropriate zone.
*
* @param array $field Field definition from Schema Registry.
* @param int $post_id Post ID.
* @param string $post_type Post type.
* @param string $meta_key Meta key.
* @param mixed $value Value to write.
* @return void
*/
private function write_to_zone( array $field, int $post_id, string $post_type, string $meta_key, mixed $value ): void {
match ( $field['zone'] ) {
'hot' => TMDO_Zone_Hot::set( $post_id, $post_type, $field['column'], $value ),
'cold' => TMDO_Zone_Cold::set( $post_id, $post_type, $meta_key, $value ),
'warm' => TMDO_Zone_Warm::set(
$post_id,
$meta_key,
is_string( $value ) ? $value : wp_json_encode( $value ),
$field['ttl'] ?? null
),
default => null,
};
}
/**
* Delete a value from the appropriate zone.
*
* @param array $field Field definition from Schema Registry.
* @param int $post_id Post ID.
* @param string $post_type Post type.
* @param string $meta_key Meta key.
* @return void
*/
private function delete_from_zone( array $field, int $post_id, string $post_type, string $meta_key ): void {
match ( $field['zone'] ) {
'hot' => TMDO_Zone_Hot::set( $post_id, $post_type, $field['column'], null ),
'cold' => TMDO_Zone_Cold::remove( $post_id, $post_type, $meta_key ),
'warm' => TMDO_Zone_Warm::delete( $post_id, $meta_key ),
default => null,
};
}
}