Squirrly keys indexed by SOOZ metadata identifier. */ function ai4seo_get_squirrly_seo_metadata_identifier_mapping(): array { // Keep custom-table reads and writes on the same serialized Squirrly keys. return array( 'meta-title' => 'title', 'meta-description' => 'description', 'keywords' => 'keywords', 'facebook-title' => 'og_title', 'facebook-description' => 'og_description', 'twitter-title' => 'tw_title', 'twitter-description' => 'tw_description', ); } /** * Collects all the currently supported and active third party SEO plugins * * @return array The supported and currently active third party SEO plugins */ function ai4seo_get_active_third_party_seo_plugin_details(): array { if ( ai4seo_prevent_loops( __FUNCTION__ ) ) { ai4seo_debug_message( 500078657, 'Prevented loop', true ); return array(); } $active_supported_third_party_seo_plugin_details = array(); $third_party_seo_plugin_details = ai4seo_get_third_party_seo_plugin_details(); foreach ( $third_party_seo_plugin_details as $this_third_party_seo_plugin_identifier => $this_third_party_seo_plugin_details ) { if ( ai4seo_is_plugin_or_theme_active( $this_third_party_seo_plugin_identifier ) ) { $active_supported_third_party_seo_plugin_details[ $this_third_party_seo_plugin_identifier ] = $this_third_party_seo_plugin_details; } } return $active_supported_third_party_seo_plugin_details; } /** * Returns active third-party integrations whose JavaScript editors require DOM discovery. * * @return array Active integration identifiers in stable initialization order. */ function ai4seo_get_active_generation_editor_integration_identifiers(): array { // Plugin activation state is request-stable, so reuse the filtered list across localization calls. static $active_generation_editor_integration_identifiers = null; if ( is_array( $active_generation_editor_integration_identifiers ) ) { return $active_generation_editor_integration_identifiers; } // Keep this order aligned with the client definition map for deterministic adapter initialization. $generation_editor_integration_identifiers = array( AI4SEO_THIRD_PARTY_PLUGIN_YOAST_SEO, AI4SEO_THIRD_PARTY_PLUGIN_ALL_IN_ONE_SEO, AI4SEO_THIRD_PARTY_PLUGIN_SEOPRESS, AI4SEO_THIRD_PARTY_PLUGIN_SLIM_SEO, AI4SEO_THIRD_PARTY_PLUGIN_SQUIRRLY_SEO, ); // Filter server-side so inactive plugins never reach JavaScript discovery or observer setup. $active_generation_editor_integration_identifiers = array(); foreach ( $generation_editor_integration_identifiers as $generation_editor_integration_identifier ) { if ( ai4seo_is_plugin_or_theme_active( $generation_editor_integration_identifier ) ) { $active_generation_editor_integration_identifiers[] = $generation_editor_integration_identifier; } } return $active_generation_editor_integration_identifiers; } /** * Returns the configured generation-field postmeta mapping for one integration. * * The third-party registry is immutable during a request, so keeping one normalized copy per * plugin avoids repeating the same nested lookup in resolvers and editor localization. * * @param string $plugin_identifier The third-party SEO plugin identifier. * @return array The generation-field postmeta keys indexed by SOOZ metadata identifier. */ function ai4seo_get_third_party_seo_plugin_generation_postmeta_keys( string $plugin_identifier ): array { // Cache normalized mappings because frontend resolution can request several fields per post. static $generation_postmeta_keys_by_plugin = array(); $plugin_identifier = sanitize_key( $plugin_identifier ); // Reject empty identifiers before using them as registry or cache keys. if ( '' === $plugin_identifier ) { return array(); } // Reuse empty mappings as well as populated ones so malformed entries are normalized only once. if ( isset( $generation_postmeta_keys_by_plugin[ $plugin_identifier ] ) ) { return $generation_postmeta_keys_by_plugin[ $plugin_identifier ]; } // Normalize malformed or missing registry entries once so callers always receive a safe array. $third_party_seo_plugin_details = ai4seo_get_third_party_seo_plugin_details(); $generation_postmeta_keys = $third_party_seo_plugin_details[ $plugin_identifier ]['generation-field-postmeta-keys'] ?? array(); $generation_postmeta_keys_by_plugin[ $plugin_identifier ] = is_array( $generation_postmeta_keys ) ? $generation_postmeta_keys : array(); return $generation_postmeta_keys_by_plugin[ $plugin_identifier ]; } /** * Returns the SOOZ metadata identifiers supported by one third-party generation mapping. * * @param string $plugin_identifier The third-party SEO plugin identifier. * @return array The supported SOOZ metadata identifiers. */ function ai4seo_get_third_party_seo_plugin_generation_metadata_identifiers( string $plugin_identifier ): array { // Cache the derived keys separately because every resolver performs the same membership check. static $metadata_identifiers_by_plugin = array(); $plugin_identifier = sanitize_key( $plugin_identifier ); // Reject empty identifiers before using them as cache keys. if ( '' === $plugin_identifier ) { return array(); } if ( ! isset( $metadata_identifiers_by_plugin[ $plugin_identifier ] ) ) { // Derive identifiers from the shared mapping so resolver field support cannot drift from synchronization. $metadata_identifiers_by_plugin[ $plugin_identifier ] = array_keys( ai4seo_get_third_party_seo_plugin_generation_postmeta_keys( $plugin_identifier ) ); } return $metadata_identifiers_by_plugin[ $plugin_identifier ]; } /** * Reads the SEOPress fields needed by its JavaScript-rendered generation editor. * * The caller decides whether the plugin and external generation controls are active; this helper * owns only integration-specific storage normalization and keeps localization type-safe. * * @param int $post_id The post whose SEOPress generation fields should be read. * @return array The normalized metadata values indexed by SOOZ metadata identifier. */ function ai4seo_get_seopress_generation_metadata_for_editor( int $post_id ): array { // Localization never needs an invalid or unresolved post context. if ( $post_id <= 0 ) { return array(); } // Read every field from the shared integration mapping so editor proxies and sync stay aligned. $seopress_generation_metadata = array(); $seopress_generation_postmeta_keys = ai4seo_get_third_party_seo_plugin_generation_postmeta_keys( AI4SEO_THIRD_PARTY_PLUGIN_SEOPRESS ); foreach ( $seopress_generation_postmeta_keys as $metadata_identifier => $postmeta_key ) { $seopress_postmeta_value = get_post_meta( $post_id, $postmeta_key, true ); // Treat malformed structured values as empty instead of emitting string-conversion warnings. if ( ! is_scalar( $seopress_postmeta_value ) ) { $seopress_postmeta_value = ''; } $seopress_generation_metadata[ $metadata_identifier ] = html_entity_decode( (string) $seopress_postmeta_value, ENT_QUOTES | ENT_XML1, 'UTF-8' ); } return $seopress_generation_metadata; } /** * Reports whether one registry entry participates in generic inbound postmeta synchronization. * * Keeping the capability interpretation here ensures hooks, outbound-loop suppression, and * settings copy continue to opt integrations in under the same rule. * * @param array $third_party_seo_plugin_details One third-party SEO plugin registry entry. * @return bool Whether generic inbound postmeta synchronization is enabled. */ function ai4seo_does_third_party_seo_plugin_support_inbound_postmeta_sync( array $third_party_seo_plugin_details ): bool { // Registry entries opt in explicitly; compound stores provide their postmeta and nested-field mapping here. return ! empty( $third_party_seo_plugin_details['inbound-postmeta-sync'] ); } /** * Reports whether one integration supports any persisted third-party-to-SOOZ synchronization path. * * @param array $third_party_seo_plugin_details One third-party SEO plugin registry entry. * @return bool Whether direct, compound, or integration-specific inbound synchronization is enabled. */ function ai4seo_does_third_party_seo_plugin_support_inbound_sync( array $third_party_seo_plugin_details ): bool { // Custom-table integrations opt in separately because postmeta hooks cannot observe their writes. return ai4seo_does_third_party_seo_plugin_support_inbound_postmeta_sync( $third_party_seo_plugin_details ) || ! empty( $third_party_seo_plugin_details['inbound-custom-sync'] ); } /** * Normalizes one compound postmeta synchronization declaration from the integration registry. * * Both inbound hooks and outbound shared-array writers use this representation so a plugin's * postmeta key and nested field mapping cannot drift between synchronization directions. * * @param array $third_party_seo_plugin_details One third-party SEO plugin registry entry. * @return array{postmeta_key: string, generation_field_array_keys: array}|array{} */ function ai4seo_get_third_party_seo_plugin_compound_postmeta_sync_details( array $third_party_seo_plugin_details ): array { // Only structured declarations describe a shared postmeta value with nested generation fields. $inbound_postmeta_sync = $third_party_seo_plugin_details['inbound-postmeta-sync'] ?? null; if ( ! is_array( $inbound_postmeta_sync ) ) { return array(); } // Normalize registry identifiers before exposing them to postmeta or active-metadata lookups. $postmeta_key = sanitize_key( $inbound_postmeta_sync['postmeta-key'] ?? '' ); $generation_field_array_keys = $inbound_postmeta_sync['generation-field-array-keys'] ?? array(); if ( ! $postmeta_key || ! is_array( $generation_field_array_keys ) ) { return array(); } $normalized_generation_field_array_keys = array(); // Preserve the registry's metadata-to-nested-key direction for outbound shared-array writes. foreach ( $generation_field_array_keys as $metadata_identifier => $array_key ) { $metadata_identifier = sanitize_key( $metadata_identifier ); $array_key = sanitize_key( $array_key ); if ( $metadata_identifier && $array_key ) { $normalized_generation_field_array_keys[ $metadata_identifier ] = $array_key; } } if ( ! $normalized_generation_field_array_keys ) { return array(); } return array( 'postmeta_key' => $postmeta_key, 'generation_field_array_keys' => $normalized_generation_field_array_keys, ); } /** * Indexes generic inbound synchronization details by third-party postmeta key. * * The global postmeta hooks use this request-local lookup to reject unrelated mutations before * post, setting, or metadata reads while retaining the registry as the integration source of truth. * * @return array Synchronization details indexed by postmeta key. */ function ai4seo_get_third_party_seo_plugin_inbound_sync_details_by_postmeta_key(): array { // Build the immutable registry-derived index once because every postmeta mutation enters the hooks. static $sync_details_by_postmeta_key = null; if ( null !== $sync_details_by_postmeta_key ) { return $sync_details_by_postmeta_key; } $sync_details_by_postmeta_key = array(); $third_party_seo_plugins = ai4seo_get_third_party_seo_plugin_details(); // Only integrations opting into generic postmeta synchronization contribute hook keys. foreach ( $third_party_seo_plugins as $plugin_identifier => $plugin_details ) { if ( ! ai4seo_does_third_party_seo_plugin_support_inbound_postmeta_sync( $plugin_details ) ) { continue; } // Compound integrations identify one postmeta key and the nested key for each SOOZ field. if ( is_array( $plugin_details['inbound-postmeta-sync'] ) ) { $compound_sync_details = ai4seo_get_third_party_seo_plugin_compound_postmeta_sync_details( $plugin_details ); if ( ! $compound_sync_details ) { continue; } // Inbound array reads need the inverse mapping because changed values arrive by nested key. $metadata_identifier_by_array_key = array_flip( $compound_sync_details['generation_field_array_keys'] ); $postmeta_key = $compound_sync_details['postmeta_key']; $sync_details_by_postmeta_key[ $postmeta_key ] = array( 'plugin_identifier' => sanitize_key( $plugin_identifier ), 'metadata_identifier_by_array_key' => $metadata_identifier_by_array_key, ); continue; } // Direct integrations need one registry postmeta key for each independently stored SOOZ field. if ( empty( $plugin_details['generation-field-postmeta-keys'] ) || ! is_array( $plugin_details['generation-field-postmeta-keys'] ) ) { continue; } // Pair each valid postmeta key with the integration and SOOZ field required by later allowlist checks. foreach ( $plugin_details['generation-field-postmeta-keys'] as $metadata_identifier => $postmeta_key ) { $metadata_identifier = sanitize_key( $metadata_identifier ); $postmeta_key = sanitize_key( $postmeta_key ); // Ignore malformed registry entries so they cannot create an empty global-hook lookup key. if ( ! $metadata_identifier || ! $postmeta_key ) { continue; } $sync_details_by_postmeta_key[ $postmeta_key ] = array( 'plugin_identifier' => sanitize_key( $plugin_identifier ), 'metadata_identifier' => $metadata_identifier, ); } } return $sync_details_by_postmeta_key; } /** * Returns metadata identifiers currently configured to sync with one active third-party SEO plugin. * * @param string $plugin_identifier The third-party SEO plugin identifier. * @return array The supported metadata identifiers that are enabled for synchronization. */ function ai4seo_get_third_party_seo_plugin_sync_metadata_identifiers( string $plugin_identifier ): array { // Normalize caller input before using it as a plugin-registry key or setting value. $plugin_identifier = sanitize_key( $plugin_identifier ); if ( ! $plugin_identifier ) { return array(); } // Live editor synchronization applies only to plugins active in the current request. $active_third_party_seo_plugin_details = ai4seo_get_active_third_party_seo_plugin_details(); if ( ! isset( $active_third_party_seo_plugin_details[ $plugin_identifier ]['generation-field-postmeta-keys'] ) || ! is_array( $active_third_party_seo_plugin_details[ $plugin_identifier ]['generation-field-postmeta-keys'] ) ) { return array(); } // Respect the plugin-level synchronization setting before considering individual metadata fields. $policy = ai4seo_read_metadata_sync_policy_snapshot(); $sync_third_party_seo_plugin_identifiers = $policy['settings'][ AI4SEO_SETTING_APPLY_CHANGES_TO_THIRD_PARTY_SEO_PLUGINS ]; if ( ! is_array( $sync_third_party_seo_plugin_identifiers ) || ! in_array( $plugin_identifier, $sync_third_party_seo_plugin_identifiers, true ) ) { return array(); } // Field-level synchronization is the final allowlist shared by modal reads and save responses. $sync_metadata_identifiers = $policy['settings'][ AI4SEO_SETTING_SYNC_ONLY_THESE_METADATA ]; if ( ! is_array( $sync_metadata_identifiers ) ) { return array(); } $supported_metadata_identifiers = array_keys( $active_third_party_seo_plugin_details[ $plugin_identifier ]['generation-field-postmeta-keys'] ); // Preserve setting order while removing fields unsupported by the requested plugin. return array_values( array_intersect( $sync_metadata_identifiers, $supported_metadata_identifiers ) ); } /** * Read synchronization/output permissions without repairing persisted settings. * * Missing keys retain installation defaults; malformed values never inherit permissions. * Positive lists retain only explicitly selected, recognized members. An incomplete * exclusion list cannot prove that a post type is permitted. * * @return array Settings, issue keys, and a fingerprint for current-state comparisons. */ function ai4seo_read_metadata_sync_policy_snapshot(): array { $lists = array( AI4SEO_SETTING_APPLY_CHANGES_TO_THIRD_PARTY_SEO_PLUGINS => array_keys( ai4seo_get_third_party_seo_plugin_details() ), AI4SEO_SETTING_SYNC_ONLY_THESE_METADATA => AI4SEO_AVAILABLE_METADATA_IDENTIFIERS, AI4SEO_SETTING_ACTIVE_META_TAGS => AI4SEO_AVAILABLE_METADATA_IDENTIFIERS, AI4SEO_SETTING_OVERWRITE_EXISTING_METADATA => AI4SEO_AVAILABLE_METADATA_IDENTIFIERS, ); $scalar_defaults = array( AI4SEO_SETTING_META_TAG_OUTPUT_MODE => 'disable', AI4SEO_SETTING_IMAGE_TITLE_INJECTION_MODE => 'disabled', AI4SEO_SETTING_ENABLE_RENDER_LEVEL_ALT_TEXT_INJECTION => false, AI4SEO_SETTING_DISABLED_POST_TYPES => null, ); try { $snapshot = ai4seo_get_raw_option_snapshot( AI4SEO_SETTINGS_OPTION_NAME ); } catch ( Throwable $throwable ) { $snapshot = null; } $stored = ai4seo_decode_settings_snapshot( $snapshot ); $result = array( 'settings' => array(), 'issues' => array(), ); foreach ( array_merge( array_keys( $lists ), array_keys( $scalar_defaults ) ) as $key ) { $value = is_array( $stored ) ? ( array_key_exists( $key, $stored ) ? $stored[ $key ] : AI4SEO_DEFAULT_SETTINGS[ $key ] ) : null; if ( isset( $lists[ $key ] ) ) { $valid = array(); foreach ( is_array( $value ) ? $value : array() as $member ) { if ( is_string( $member ) && in_array( $member, $lists[ $key ], true ) ) { $valid[] = $member; } else { $result['issues'][ $key ] = true; } } if ( ! is_array( $value ) ) { $result['issues'][ $key ] = true; } $result['settings'][ $key ] = array_values( array_unique( $valid ) ); } else { $value = ai4seo_normalize_boolean_setting_value( $key, $value ); $valid = null !== $value; if ( AI4SEO_SETTING_DISABLED_POST_TYPES === $key ) { $valid = is_array( $value ); foreach ( is_array( $value ) ? $value : array() as $type ) { $valid = $valid && is_string( $type ) && '' !== $type && sanitize_key( $type ) === $type; } } else { $allowed = AI4SEO_SETTING_META_TAG_OUTPUT_MODE === $key ? AI4SEO_AVAILABLE_META_TAG_OUTPUT_MODE_OPTIONS : ( AI4SEO_SETTING_IMAGE_TITLE_INJECTION_MODE === $key ? AI4SEO_AVAILABLE_IMAGE_TITLE_INJECTION_MODE_OPTIONS : array( true, false ) ); $valid = $valid && in_array( $value, $allowed, true ); } $result['settings'][ $key ] = $valid ? $value : $scalar_defaults[ $key ]; if ( ! $valid ) { $result['issues'][ $key ] = true; } } } $result['fingerprint'] = hash( 'sha256', wp_json_encode( $result ) ); return $result; } /** * Explain restricted settings without exposing stored values or changing them. * * @param array $policy Current policy snapshot. * @return array Translated warnings shared by save responses and administration. */ function ai4seo_get_metadata_sync_policy_warnings( array $policy ): array { if ( ! $policy['issues'] ) { return array(); } return array( __( 'Some SEO synchronization or output settings could not be read reliably. Only explicitly permitted targets and fields are used; affected output remains unchanged. Stored settings were not repaired.', 'ai-for-seo' ) ); } /** * Render the read-only troubleshooting notice from current policy evidence. * * @param array $policy Current policy snapshot. * @return string Escaped administration HTML, empty for healthy settings. */ function ai4seo_get_metadata_sync_policy_notice_html( array $policy ): string { $html = ''; foreach ( ai4seo_get_metadata_sync_policy_warnings( $policy ) as $warning ) { $html .= '

' . esc_html__( 'SEO synchronization and output restricted', 'ai-for-seo' ) . '

' . esc_html( $warning ) . '

'; } return $html; } /** * Check one real entry without relying on a cached inventory of populated types. * * @param int $post_id Entry ID. * @param array|null $policy Optional current policy. * @return bool Whether current registration and exclusions permit metadata. */ function ai4seo_is_metadata_sync_post_supported( int $post_id, ?array $policy = null ): bool { $post = get_post( $post_id ); $policy = $policy ?? ai4seo_read_metadata_sync_policy_snapshot(); $disabled = $policy['settings'][ AI4SEO_SETTING_DISABLED_POST_TYPES ]; return $post instanceof WP_Post && is_array( $disabled ) && isset( ai4seo_get_publicly_accessible_post_types()[ $post->post_type ] ) && ! in_array( $post->post_type, $disabled, true ); } /** * Read a provider through the shared reader, retaining only reliable requested fields. * * @param int $post_id Entry ID. * @param string $provider Provider identifier. * @param array $fields Relevant fields, never inferred from an event's values. * @return array Values, unknown fields, and comparison fingerprint. */ function ai4seo_read_third_party_metadata_sync_snapshot( int $post_id, string $provider, array $fields ): array { $issues = array(); $succeeded = false; try { $rows = ai4seo_read_third_party_seo_plugin_metadata_by_post_ids( $provider, array( $post_id ), $succeeded, $issues ); } catch ( Throwable $throwable ) { $rows = array(); $succeeded = false; } if ( in_array( $provider, array( AI4SEO_THIRD_PARTY_PLUGIN_SQUIRRLY_SEO, AI4SEO_THIRD_PARTY_PLUGIN_ALL_IN_ONE_SEO ), true ) && ! isset( $rows[ $post_id ] ) ) { $succeeded = false; } if ( AI4SEO_THIRD_PARTY_PLUGIN_SLIM_SEO === $provider ) { $exact_succeeded = false; try { $exact_rows = ai4seo_read_exact_third_party_postmeta_rows( $post_id, 'slim_seo', $exact_succeeded ); } catch ( Throwable $throwable ) { $exact_rows = array(); $exact_succeeded = false; } $succeeded = $succeeded && $exact_succeeded && count( $exact_rows ) <= 1; } $result = array( 'values' => array(), 'unknown' => array(), ); foreach ( $fields as $field ) { $value = $rows[ $post_id ][ $field ] ?? ''; if ( ! $succeeded || ai4seo_is_posts_table_analysis_field_unknown( $issues, $post_id, $field ) || ! is_string( $value ) || is_serialized( $value ) ) { $result['unknown'][] = $field; } else { $result['values'][ $field ] = $value; } } $result['fingerprint'] = hash( 'sha256', wp_json_encode( $result ) ); return $result; } /** * Revalidate source and permission under the active-metadata writer's lock. * * @param int $post_id Entry ID. * @param array $context Optional internal synchronization preconditions. * @return bool Whether the source is still authoritative for this write. */ function ai4seo_validate_metadata_sync_source( int $post_id, array $context ): bool { if ( ! empty( $context['taxonomy_generation'] ) ) { return ai4seo_validate_taxonomy_generation_write( $post_id, $context ); } if ( ! empty( $context['taxonomy_proxy'] ) ) { return ai4seo_is_database_advisory_lock_owned_by_current_connection( ai4seo_get_taxonomy_proxy_sync_lock_name() ) && ai4seo_can_edit_taxonomy_proxy( $post_id ); } if ( ! isset( $context['sync_source'] ) ) { return true; } $source = $context['sync_source']; $policy = ai4seo_read_metadata_sync_policy_snapshot(); $current = ai4seo_read_third_party_metadata_sync_snapshot( $post_id, $source['provider'], $source['fields'] ); return hash_equals( $source['policy'], $policy['fingerprint'] ) && ai4seo_is_metadata_sync_post_supported( $post_id, $policy ) && hash_equals( $source['fingerprint'], $current['fingerprint'] ); } /** * Mirror the current reliable subset, preserving unknown fields and all source rows. * * @param int $post_id Entry ID. * @param string $provider Provider identifier. * @param array $fields Fields affected by the persisted event. * @return bool Whether every eligible field was synchronized. */ function ai4seo_sync_current_third_party_metadata( int $post_id, string $provider, array $fields ): bool { $state = ai4seo_manage_third_party_seo_metadata_sync_request_state( 'read' ); if ( ! empty( $state['outbound_sync_depth_by_post_id'][ $post_id ] ) || isset( $state['deleting_post_ids'][ $post_id ] ) ) { return true; } $fields = array_values( array_intersect( $fields, ai4seo_get_third_party_seo_plugin_sync_metadata_identifiers( $provider ) ) ); if ( ! $fields ) { return true; } $policy = ai4seo_read_metadata_sync_policy_snapshot(); $snapshot = ai4seo_read_third_party_metadata_sync_snapshot( $post_id, $provider, $fields ); $context = array( 'preserve_storage' => true, 'sync_source' => array( 'provider' => $provider, 'fields' => $fields, 'policy' => $policy['fingerprint'], 'fingerprint' => $snapshot['fingerprint'], ), ); $saved = ! $snapshot['values'] || ai4seo_sync_third_party_metadata_values_to_active_metadata( $post_id, $provider, $snapshot['values'], false, $context ); if ( $snapshot['unknown'] || ! $saved ) { ai4seo_debug_message( 418620970, 'SEO synchronization restricted for post ' . $post_id . ', provider ' . $provider . ', fields: ' . implode( ', ', $snapshot['unknown'] ? $snapshot['unknown'] : $fields ), true ); } return $saved && ! $snapshot['unknown']; } /** * Returns stable display names for third-party SEO plugin identifiers. * * @param array $plugin_identifiers Plugin identifiers. * @return array */ function ai4seo_get_third_party_seo_plugin_names( array $plugin_identifiers ): array { $third_party_seo_plugins = ai4seo_get_third_party_seo_plugin_details(); $plugin_names = array(); // Prefer registry labels while retaining an identifier fallback for future or removed integrations. foreach ( array_unique( array_map( 'sanitize_key', $plugin_identifiers ) ) as $plugin_identifier ) { $plugin_name = $third_party_seo_plugins[ $plugin_identifier ]['name'] ?? $plugin_identifier; $plugin_name = sanitize_text_field( (string) $plugin_name ); if ( '' !== $plugin_name ) { $plugin_names[] = $plugin_name; } } // Stable sorting keeps manual errors and cron activity details deterministic across registry order changes. $plugin_names = array_values( array_unique( $plugin_names ) ); sort( $plugin_names, SORT_NATURAL | SORT_FLAG_CASE ); return $plugin_names; } /** * Returns the primary focus keyphrase represented by one third-party SEO plugin value. * * Rank Math stores secondary focus keywords after the primary value in one comma-separated * postmeta string, while SOOZ and the other supported integrations expose one primary phrase. * * @param string $plugin_identifier The third-party SEO plugin identifier. * @param string $focus_keyphrase The sanitized integration value. * @return string The primary focus keyphrase. */ function ai4seo_get_primary_third_party_seo_plugin_focus_keyphrase( string $plugin_identifier, string $focus_keyphrase ): string { $focus_keyphrase = trim( $focus_keyphrase ); // Match Rank Math's own primary-keyword behavior without treating commas from other integrations as separators. if ( AI4SEO_THIRD_PARTY_PLUGIN_RANK_MATH === $plugin_identifier ) { $rank_math_focus_keyphrases = explode( ',', $focus_keyphrase, 2 ); $focus_keyphrase = trim( $rank_math_focus_keyphrases[0] ?? '' ); } return $focus_keyphrase; } /** * Manages request-local state for persisted third-party-to-SOOZ metadata synchronization. * * Supported operations are read, begin-outbound, end-outbound, mark-deleting, * mark-changed, mark-squirrly-synced, consume-changed, requeue-site-state, * and requeue-network-fallback. * * @param string $operation The state operation to perform. * @param int $post_id The optional post id associated with the operation. * @param array $origin_site_state Optional consumed origin-site state to requeue after finalization failure. * @return array The complete request-local synchronization state. */ function ai4seo_manage_third_party_seo_metadata_sync_request_state( string $operation, int $post_id = 0, array $origin_site_state = array() ): array { global $wpdb; // Keep nested outbound writes and per-post queues isolated to their originating site's storage. static $state_by_site_scope = array(); static $changed_site_scope_index = array(); static $requires_network_fallback = false; // Normalize internal callers so state keys always use the same post-id representation. $operation = sanitize_key( $operation ); $post_id = absint( $post_id ); $blog_id = absint( get_current_blog_id() ); $options_table = isset( $wpdb->options ) ? (string) $wpdb->options : ''; $postmeta_table = isset( $wpdb->postmeta ) ? (string) $wpdb->postmeta : ''; $site_scope_key = $options_table . '|' . $postmeta_table . '|' . $blog_id; if ( ! isset( $state_by_site_scope[ $site_scope_key ] ) ) { $state_by_site_scope[ $site_scope_key ] = array( 'blog_id' => $blog_id, 'options_table' => $options_table, 'postmeta_table' => $postmeta_table, 'outbound_sync_depth_by_post_id' => array(), 'deleting_post_ids' => array(), 'changed_post_ids' => array(), 'squirrly_synced_post_ids' => array(), 'requires_full_rebuild' => false, ); } $state =& $state_by_site_scope[ $site_scope_key ]; if ( 'requeue-network-fallback' === $operation ) { $requires_network_fallback = true; return $state; } if ( 'requeue-site-state' === $operation ) { $origin_blog_id = absint( $origin_site_state['blog_id'] ?? 0 ); $origin_options_table = isset( $origin_site_state['options_table'] ) ? (string) $origin_site_state['options_table'] : ''; $origin_postmeta_table = isset( $origin_site_state['postmeta_table'] ) ? (string) $origin_site_state['postmeta_table'] : ''; $origin_scope_key = $origin_options_table . '|' . $origin_postmeta_table . '|' . $origin_blog_id; $changed_post_ids = isset( $origin_site_state['changed_post_ids'] ) && is_array( $origin_site_state['changed_post_ids'] ) ? array_keys( $origin_site_state['changed_post_ids'] ) : array(); $requires_full_rebuild = ! empty( $origin_site_state['requires_full_rebuild'] ); if ( $origin_blog_id <= 0 || '' === $origin_options_table || '' === $origin_postmeta_table || ( ! $changed_post_ids && ! $requires_full_rebuild ) ) { return $state; } if ( isset( $state_by_site_scope[ $origin_scope_key ] ) && ( absint( $state_by_site_scope[ $origin_scope_key ]['blog_id'] ?? 0 ) !== $origin_blog_id || (string) ( $state_by_site_scope[ $origin_scope_key ]['options_table'] ?? '' ) !== $origin_options_table || (string) ( $state_by_site_scope[ $origin_scope_key ]['postmeta_table'] ?? '' ) !== $origin_postmeta_table ) ) { return $state; } if ( ! isset( $changed_site_scope_index[ $origin_scope_key ] ) && count( $changed_site_scope_index ) >= ai4seo_get_third_party_seo_metadata_finalization_retry_scope_limit() ) { $requires_network_fallback = true; return $state; } $changed_site_scope_index[ $origin_scope_key ] = true; if ( ! isset( $state_by_site_scope[ $origin_scope_key ] ) ) { $state_by_site_scope[ $origin_scope_key ] = array( 'blog_id' => $origin_blog_id, 'options_table' => $origin_options_table, 'postmeta_table' => $origin_postmeta_table, 'outbound_sync_depth_by_post_id' => array(), 'deleting_post_ids' => array(), 'changed_post_ids' => array(), 'squirrly_synced_post_ids' => array(), 'requires_full_rebuild' => false, ); } $origin_state =& $state_by_site_scope[ $origin_scope_key ]; if ( $requires_full_rebuild ) { $origin_state['changed_post_ids'] = array(); $origin_state['requires_full_rebuild'] = true; return $origin_state; } $exact_post_id_limit = ai4seo_get_third_party_seo_metadata_finalization_retry_post_id_limit(); foreach ( $changed_post_ids as $changed_post_id ) { $changed_post_id = absint( $changed_post_id ); if ( $changed_post_id <= 0 || $origin_state['requires_full_rebuild'] || isset( $origin_state['deleting_post_ids'][ $changed_post_id ] ) || isset( $origin_state['changed_post_ids'][ $changed_post_id ] ) ) { continue; } if ( count( $origin_state['changed_post_ids'] ) < $exact_post_id_limit ) { $origin_state['changed_post_ids'][ $changed_post_id ] = true; } else { $origin_state['changed_post_ids'] = array(); $origin_state['requires_full_rebuild'] = true; } } return $origin_state; } if ( 'consume-changed' === $operation ) { // Consume only the bounded changed-origin index; unrelated guard state is never scanned or discarded. $consumed_state = $state; $consumed_state['site_states'] = array(); $consumed_state['requires_network_fallback'] = $requires_network_fallback; foreach ( array_keys( $changed_site_scope_index ) as $this_site_scope_key ) { if ( ! isset( $state_by_site_scope[ $this_site_scope_key ] ) ) { continue; } $this_site_state =& $state_by_site_scope[ $this_site_scope_key ]; if ( ! empty( $this_site_state['changed_post_ids'] ) || ! empty( $this_site_state['requires_full_rebuild'] ) ) { $consumed_state['site_states'][ $this_site_scope_key ] = $this_site_state; } $this_site_state['changed_post_ids'] = array(); $this_site_state['requires_full_rebuild'] = false; if ( ! $this_site_state['outbound_sync_depth_by_post_id'] && ! $this_site_state['deleting_post_ids'] && ! $this_site_state['squirrly_synced_post_ids'] ) { unset( $this_site_state ); unset( $state_by_site_scope[ $this_site_scope_key ] ); } } unset( $this_site_state ); $changed_site_scope_index = array(); $requires_network_fallback = false; return $consumed_state; } // Centralize all state transitions so outbound guards and shutdown finalization stay paired. switch ( $operation ) { case 'begin-outbound': // Scope nested suppression to the originating post so related-post integrations remain independent. if ( $post_id > 0 ) { $current_depth = $state['outbound_sync_depth_by_post_id'][ $post_id ] ?? 0; $state['outbound_sync_depth_by_post_id'][ $post_id ] = $current_depth + 1; } break; case 'end-outbound': // Remove completed counters so the state reflects only posts with active outbound writes. if ( $post_id > 0 && isset( $state['outbound_sync_depth_by_post_id'][ $post_id ] ) ) { $current_depth = max( 0, $state['outbound_sync_depth_by_post_id'][ $post_id ] - 1 ); if ( $current_depth > 0 ) { $state['outbound_sync_depth_by_post_id'][ $post_id ] = $current_depth; } else { unset( $state['outbound_sync_depth_by_post_id'][ $post_id ] ); } } break; case 'mark-deleting': // A permanently deleted post must not be refreshed or recreated by later meta-delete hooks. if ( $post_id > 0 ) { $state['deleting_post_ids'][ $post_id ] = true; unset( $state['changed_post_ids'][ $post_id ] ); if ( ! $state['changed_post_ids'] && ! $state['requires_full_rebuild'] ) { unset( $changed_site_scope_index[ $site_scope_key ] ); } } break; case 'mark-changed': // Keying by post id collapses several third-party field writes into one shutdown refresh. // Once the exact-ID budget is exhausted, one full rebuild is the bounded superset repair. if ( $post_id > 0 && ! $state['requires_full_rebuild'] ) { $exact_post_id_limit = ai4seo_get_third_party_seo_metadata_finalization_retry_post_id_limit(); if ( ! isset( $changed_site_scope_index[ $site_scope_key ] ) && count( $changed_site_scope_index ) >= ai4seo_get_third_party_seo_metadata_finalization_retry_scope_limit() ) { $requires_network_fallback = true; if ( ! $state['outbound_sync_depth_by_post_id'] && ! $state['deleting_post_ids'] && ! $state['changed_post_ids'] && ! $state['squirrly_synced_post_ids'] ) { $overflow_state = $state; unset( $state ); unset( $state_by_site_scope[ $site_scope_key ] ); return $overflow_state; } break; } $changed_site_scope_index[ $site_scope_key ] = true; if ( isset( $state['changed_post_ids'][ $post_id ] ) ) { break; } if ( count( $state['changed_post_ids'] ) < $exact_post_id_limit ) { $state['changed_post_ids'][ $post_id ] = true; } else { $state['changed_post_ids'] = array(); $state['requires_full_rebuild'] = true; } } break; case 'mark-squirrly-synced': // Prevent Squirrly's later save_post fallback from repeating a completed editor-save synchronization. if ( $post_id > 0 ) { $state['squirrly_synced_post_ids'][ $post_id ] = true; } break; case 'read': // Callers receive the current snapshot without mutating request state. break; } return $state; } /** * Marks a post as being permanently deleted so removed third-party fields are not recreated in SOOZ. * * @param int $post_id The post id being deleted. * @return void */ function ai4seo_track_deleting_post_for_third_party_seo_metadata_sync( int $post_id ): void { // Mark before WordPress deletes postmeta, because those delete hooks run while the post is being removed. ai4seo_manage_third_party_seo_metadata_sync_request_state( 'mark-deleting', $post_id ); } /** * Mirrors persisted third-party metadata values into SOOZ active metadata. * * @param int $post_id The post whose metadata changed. * @param string $plugin_identifier The originating third-party SEO plugin. * @param array $raw_metadata_values Raw values indexed by SOOZ metadata identifier. * @param bool $values_were_deleted Whether every supplied field represents an explicit deletion. * @param array $sync_context Optional current-source preconditions for persisted hooks. * @return bool Whether the requested SOOZ state was reached or no eligible change was required. */ function ai4seo_sync_third_party_metadata_values_to_active_metadata( int $post_id, string $plugin_identifier, array $raw_metadata_values, bool $values_were_deleted = false, array $sync_context = array() ): bool { // Normalize hook and integration inputs before any post, setting, or active-metadata work. $post_id = absint( $post_id ); $plugin_identifier = sanitize_key( $plugin_identifier ); if ( $post_id <= 0 || ! $plugin_identifier || wp_is_post_revision( $post_id ) ) { return false; } // Ignore writes originating from SOOZ and metadata changes associated with permanent post deletion. $request_state = ai4seo_manage_third_party_seo_metadata_sync_request_state( 'read' ); if ( ! empty( $request_state['outbound_sync_depth_by_post_id'][ $post_id ] ) || isset( $request_state['deleting_post_ids'][ $post_id ] ) ) { return true; } // Active metadata is supported only for the post types already exposed by SOOZ. $post = get_post( $post_id ); if ( ! $post instanceof WP_Post || ! ai4seo_is_metadata_sync_post_supported( $post_id ) ) { return false; } // Both synchronization directions share the selected plugin and field allowlists. $sync_metadata_identifiers = ai4seo_get_third_party_seo_plugin_sync_metadata_identifiers( $plugin_identifier ); $metadata_values = array(); foreach ( $raw_metadata_values as $metadata_identifier => $raw_metadata_value ) { $metadata_identifier = sanitize_key( $metadata_identifier ); if ( ! in_array( $metadata_identifier, $sync_metadata_identifiers, true ) ) { continue; } // Persist explicit deletions and null defaults while rejecting unexpected structured values. if ( $values_were_deleted || null === $raw_metadata_value ) { $metadata_value = ''; } elseif ( ! is_scalar( $raw_metadata_value ) ) { continue; } else { $metadata_value = ai4seo_sanitize_editor_field_value( $raw_metadata_value ); } if ( 'focus-keyphrase' === $metadata_identifier ) { $metadata_value = ai4seo_get_primary_third_party_seo_plugin_focus_keyphrase( $plugin_identifier, $metadata_value ); } $metadata_values[ $metadata_identifier ] = $metadata_value; } if ( ! $metadata_values ) { return true; } // Reuse active-metadata normalization so inbound values follow the existing schema and length limits. $prepared_metadata = ai4seo_prepare_active_metadata_values( $metadata_values, false ); if ( ! $prepared_metadata ) { return false; } // Let the locked authoritative writer decide both the merge base and whether storage changed. $active_metadata_operation_details = array(); $sync_context['preserve_storage'] = true; $active_metadata_succeeded = ai4seo_save_active_metadata_to_postmeta( $post_id, $prepared_metadata, false, $active_metadata_operation_details, array(), array(), $sync_context ); $active_metadata_commit_state = isset( $active_metadata_operation_details['commit_state'] ) && is_string( $active_metadata_operation_details['commit_state'] ) && in_array( $active_metadata_operation_details['commit_state'], array( 'not_committed', 'committed', 'possibly_committed' ), true ) ? $active_metadata_operation_details['commit_state'] : 'possibly_committed'; $active_metadata_may_have_changed = ! empty( $active_metadata_operation_details['active_metadata_changed'] ) || 'not_committed' !== $active_metadata_commit_state; if ( $active_metadata_may_have_changed ) { // A failed readback or release still needs durable derived-state reconciliation at shutdown. ai4seo_manage_third_party_seo_metadata_sync_request_state( 'mark-changed', $post_id ); } if ( ! $active_metadata_succeeded ) { ai4seo_debug_message( 731948205, 'Could not synchronize persisted ' . $plugin_identifier . ' metadata to SOOZ for post id ' . $post_id . '.', true ); return false; } if ( ! $active_metadata_may_have_changed ) { return true; } return true; } /** * Mirrors one supported persisted third-party postmeta change into SOOZ active metadata. * * @param mixed $meta_id_or_ids The affected postmeta id or ids supplied by WordPress. * @param int $post_id The post id whose metadata changed. * @param string $meta_key The changed postmeta key. * @param mixed $meta_value The persisted postmeta value. * @return void */ function ai4seo_sync_third_party_postmeta_change_to_active_metadata( $meta_id_or_ids, int $post_id, string $meta_key, $meta_value ): void { // WordPress supplies row ids for these hooks, but synchronization is keyed by post and metadata field. unset( $meta_id_or_ids ); // Resolve the changed postmeta key before post, setting, or supported-type reads enter this global hook path. $sync_details_by_postmeta_key = ai4seo_get_third_party_seo_plugin_inbound_sync_details_by_postmeta_key(); $meta_key = sanitize_key( $meta_key ); $sync_details = $sync_details_by_postmeta_key[ $meta_key ] ?? array(); $third_party_seo_plugin_identifier = $sync_details['plugin_identifier'] ?? ''; $metadata_identifier = $sync_details['metadata_identifier'] ?? ''; $metadata_identifier_by_array_key = $sync_details['metadata_identifier_by_array_key'] ?? array(); $has_compound_metadata_field_mapping = is_array( $metadata_identifier_by_array_key ) && ! empty( $metadata_identifier_by_array_key ); if ( ! $third_party_seo_plugin_identifier || ( ! $metadata_identifier && ! $has_compound_metadata_field_mapping ) ) { return; } // Event payloads can be stale, and deletion may leave another physical row behind. unset( $meta_value ); ai4seo_sync_current_third_party_metadata( $post_id, $third_party_seo_plugin_identifier, $has_compound_metadata_field_mapping ? array_values( $metadata_identifier_by_array_key ) : array( $metadata_identifier ) ); } /** * Mirrors Squirrly's persisted custom-table metadata into SOOZ. * * @param int $post_id The post whose Squirrly metadata should be synchronized. * @return bool Whether the saved state was synchronized or already matched SOOZ. */ function ai4seo_sync_squirrly_seo_metadata_to_active_metadata( int $post_id ): bool { // Normalize hook and request values before any plugin, setting, or custom-table work. $post_id = absint( $post_id ); if ( $post_id <= 0 || wp_is_post_revision( $post_id ) ) { return false; } // Reject unsupported post types before entering Squirrly's unindexed serialized-row lookup. $post = get_post( $post_id ); if ( ! $post instanceof WP_Post || ! ai4seo_is_metadata_sync_post_supported( $post_id ) ) { return false; } // Avoid querying Squirrly's custom table when the plugin is inactive or no shared fields are enabled. if ( ! ai4seo_is_plugin_or_theme_active( AI4SEO_THIRD_PARTY_PLUGIN_SQUIRRLY_SEO ) ) { return false; } if ( ! ai4seo_get_third_party_seo_plugin_sync_metadata_identifiers( AI4SEO_THIRD_PARTY_PLUGIN_SQUIRRLY_SEO ) ) { return true; } return ai4seo_sync_current_third_party_metadata( $post_id, AI4SEO_THIRD_PARTY_PLUGIN_SQUIRRLY_SEO, ai4seo_get_third_party_seo_plugin_sync_metadata_identifiers( AI4SEO_THIRD_PARTY_PLUGIN_SQUIRRLY_SEO ) ); } /** * Synchronizes Squirrly after its own purple Save button successfully persists the snippet. * * Squirrly's sq_save_seo_after action does not pass the post id, so use the same request field * that its successful AJAX save handler already validated and persisted. * * @return void */ function ai4seo_sync_squirrly_seo_editor_save_to_active_metadata(): void { // Squirrly has used several post-id request keys across its editor save paths. $post_id = 0; foreach ( array( 'post_id', 'post_ID', 'ID' ) as $post_id_request_key ) { // phpcs:ignore WordPress.Security.NonceVerification.Recommended -- Squirrly's verified post-save hook owns nonce validation. if ( ! isset( $_REQUEST[ $post_id_request_key ] ) || ! is_scalar( $_REQUEST[ $post_id_request_key ] ) ) { continue; } // phpcs:ignore WordPress.Security.NonceVerification.Recommended -- Squirrly's verified post-save hook owns nonce validation. $post_id = absint( wp_unslash( $_REQUEST[ $post_id_request_key ] ) ); if ( $post_id > 0 ) { break; } } if ( $post_id > 0 && ai4seo_sync_squirrly_seo_metadata_to_active_metadata( $post_id ) ) { // Squirrly can fire this action from its save_post callback before SOOZ's priority-30 fallback. ai4seo_manage_third_party_seo_metadata_sync_request_state( 'mark-squirrly-synced', $post_id ); } } /** * Synchronizes Squirrly after the normal WordPress page or post Save flow completes its writes. * * @param int $post_id The saved post id. * @param WP_Post $post The saved post object. * @return void */ function ai4seo_sync_squirrly_seo_post_save_to_active_metadata( int $post_id, WP_Post $post ): void { // Autosaves, revisions, and non-public lifecycle placeholders must not replace persisted SOOZ metadata. if ( wp_is_post_autosave( $post_id ) || wp_is_post_revision( $post_id ) || 'auto-draft' === $post->post_status || 'inherit' === $post->post_status ) { return; } // Squirrly's successful editor-save action already exposed its final row earlier in this request. $request_state = ai4seo_manage_third_party_seo_metadata_sync_request_state( 'read' ); if ( isset( $request_state['squirrly_synced_post_ids'][ $post_id ] ) ) { return; } // Reuse the editor-save path so both save mechanisms normalize and merge the same persisted row. ai4seo_sync_squirrly_seo_metadata_to_active_metadata( $post_id ); } /** * Returns the site-local option that retains unfinished third-party finalization work. * * @return string Durable retry-ledger option name. */ function ai4seo_get_third_party_seo_metadata_finalization_retry_option_name(): string { return 'ai4seo_third_party_seo_metadata_finalization_retries'; } /** * Returns the maximum exact post-ID retry entries retained for one origin site. * * Larger batches collapse to one full-rebuild marker so a permanently unreachable * site cannot grow the dispatcher site's retry option without bound. * * @return int Maximum exact post-ID retry entries per origin. */ function ai4seo_get_third_party_seo_metadata_finalization_retry_post_id_limit(): int { return 32; } /** * Returns the maximum number of exact origin scopes retained in the dispatcher ledger. * * Additional origins collapse into one bounded all-sites rebuild generation instead of * growing one request's shutdown work or option storage without limit. * * @return int Maximum exact durable origin records. */ function ai4seo_get_third_party_seo_metadata_finalization_retry_scope_limit(): int { return 32; } /** * Returns the maximum number of exact durable origins processed by one finalizer invocation. * * @return int Maximum exact durable origins per invocation. */ function ai4seo_get_third_party_seo_metadata_finalization_scope_work_limit(): int { return 4; } /** * Returns the number of durable retry origins or network sites claimed before one switch. * * Advancing one cursor item at a time lets a later invocation move past an origin whose * site restoration remains ambiguous without collapsing bounded same-request preownership. * * @return int Maximum durable recovery items per claim. */ function ai4seo_get_third_party_seo_metadata_finalization_recovery_claim_limit(): int { return 1; } /** * Returns the stable key for one originating site's third-party finalization work. * * @param array $site_state Origin site identity. * @return string Scope key, or an empty string for incomplete identity. */ function ai4seo_get_third_party_seo_metadata_finalization_retry_scope_key( array $site_state ): string { $blog_id = absint( $site_state['blog_id'] ?? 0 ); $options_table = isset( $site_state['options_table'] ) ? (string) $site_state['options_table'] : ''; $postmeta_table = isset( $site_state['postmeta_table'] ) ? (string) $site_state['postmeta_table'] : ''; if ( $blog_id <= 0 || '' === $options_table || '' === $postmeta_table ) { return ''; } return hash( 'sha256', $options_table . "\0" . $postmeta_table . "\0" . $blog_id ); } /** * Returns the empty versioned durable finalization ledger. * * @return array Empty normalized ledger state. */ function ai4seo_get_empty_third_party_seo_metadata_finalization_retry_ledger(): array { return array( 'version' => 1, 'records' => array(), 'cursor' => '', 'network_fallback' => array( 'active_token' => '', 'restart_token' => '', 'last_blog_id' => 0, ), ); } /** * Validates one bounded retry-generation token. * * @param mixed $retry_token Candidate durable token. * @param bool $allow_empty Whether the idle empty token is valid. * @return bool Whether the token has the bounded plugin-owned shape. */ function ai4seo_is_valid_third_party_seo_metadata_finalization_retry_token( $retry_token, bool $allow_empty = false ): bool { if ( ! is_string( $retry_token ) ) { return false; } if ( '' === $retry_token ) { return $allow_empty; } return strlen( $retry_token ) <= 64 && 1 === preg_match( '/\A[A-Za-z0-9_.-]+\z/', $retry_token ); } /** * Normalizes the exact origin records stored inside the durable ledger. * * @param mixed $raw_records Stored origin records. * @param bool $enforce_scope_limit Whether the versioned-envelope scope cap must be enforced. * @return array|null Normalized records, or null for oversized/corrupt storage. */ function ai4seo_normalize_third_party_seo_metadata_finalization_retry_record_collection( $raw_records, bool $enforce_scope_limit = true ): ?array { if ( ! is_array( $raw_records ) || ( $enforce_scope_limit && count( $raw_records ) > ai4seo_get_third_party_seo_metadata_finalization_retry_scope_limit() ) ) { return null; } $normalized_records = array(); $allowed_record_keys = array( 'blog_id', 'options_table', 'postmeta_table', 'post_id_tokens', 'requires_full_rebuild', ); foreach ( $raw_records as $scope_key => $raw_record ) { if ( ! is_string( $scope_key ) || 1 !== preg_match( '/\A[a-f0-9]{64}\z/', $scope_key ) || ! is_array( $raw_record ) || array_diff( array_keys( $raw_record ), $allowed_record_keys ) ) { return null; } $blog_id = ai4seo_normalize_database_id( $raw_record['blog_id'] ?? null ); $options_table = $raw_record['options_table'] ?? null; $postmeta_table = $raw_record['postmeta_table'] ?? null; $post_id_tokens = $raw_record['post_id_tokens'] ?? null; $full_rebuild_token = $raw_record['requires_full_rebuild'] ?? null; if ( false === $blog_id || ! is_string( $options_table ) || ! is_string( $postmeta_table ) || strlen( $options_table ) > 64 || strlen( $postmeta_table ) > 64 || ! ai4seo_is_valid_database_identifier( $options_table ) || ! ai4seo_is_valid_database_identifier( $postmeta_table ) || ! is_array( $post_id_tokens ) || ! ai4seo_is_valid_third_party_seo_metadata_finalization_retry_token( $full_rebuild_token, true ) ) { return null; } $normalized_scope_key = ai4seo_get_third_party_seo_metadata_finalization_retry_scope_key( array( 'blog_id' => $blog_id, 'options_table' => $options_table, 'postmeta_table' => $postmeta_table, ) ); if ( '' === $normalized_scope_key || ! hash_equals( $normalized_scope_key, $scope_key ) ) { return null; } $exact_post_id_limit = ai4seo_get_third_party_seo_metadata_finalization_retry_post_id_limit(); if ( count( $post_id_tokens ) > $exact_post_id_limit ) { return null; } $normalized_post_id_tokens = array(); foreach ( $post_id_tokens as $post_id => $retry_token ) { $post_id = ai4seo_normalize_database_id( $post_id ); if ( false === $post_id || ! ai4seo_is_valid_third_party_seo_metadata_finalization_retry_token( $retry_token ) || isset( $normalized_post_id_tokens[ $post_id ] ) ) { return null; } $normalized_post_id_tokens[ $post_id ] = $retry_token; } if ( '' !== $full_rebuild_token ) { // A verified full analysis supersedes every exact per-post retry for this origin. $normalized_post_id_tokens = array(); } if ( ! $normalized_post_id_tokens && '' === $full_rebuild_token ) { continue; } ksort( $normalized_post_id_tokens, SORT_NUMERIC ); $normalized_records[ $scope_key ] = array( 'blog_id' => $blog_id, 'options_table' => $options_table, 'postmeta_table' => $postmeta_table, 'post_id_tokens' => $normalized_post_id_tokens, 'requires_full_rebuild' => $full_rebuild_token, ); } ksort( $normalized_records, SORT_STRING ); return $normalized_records; } /** * Normalizes the bounded versioned durable third-party finalization ledger. * * A pre-envelope record map remains readable for the one-way deployment migration. * * @param mixed $raw_ledger Stored option value. * @return array|null Normalized ledger, or null when storage is ambiguous/corrupt. */ function ai4seo_normalize_third_party_seo_metadata_finalization_retry_ledger( $raw_ledger ): ?array { $empty_ledger = ai4seo_get_empty_third_party_seo_metadata_finalization_retry_ledger(); if ( null === $raw_ledger || array() === $raw_ledger ) { return $empty_ledger; } if ( ! is_array( $raw_ledger ) ) { return null; } if ( ! array_key_exists( 'version', $raw_ledger ) ) { // The legacy record map had no global origin cap. Validate every decoded node before retaining a // deterministic exact subset, then cover every excess origin with one constant-size full sweep. $legacy_records = ai4seo_normalize_third_party_seo_metadata_finalization_retry_record_collection( $raw_ledger, false ); if ( null === $legacy_records ) { return null; } $scope_limit = ai4seo_get_third_party_seo_metadata_finalization_retry_scope_limit(); if ( count( $legacy_records ) > $scope_limit ) { $canonical_legacy_records = wp_json_encode( $legacy_records ); if ( ! is_string( $canonical_legacy_records ) || '' === $canonical_legacy_records ) { return null; } $empty_ledger['network_fallback']['active_token'] = hash( 'sha256', $canonical_legacy_records ); $legacy_records = array_slice( $legacy_records, 0, $scope_limit, true ); } $empty_ledger['records'] = $legacy_records; return $empty_ledger; } $allowed_ledger_keys = array( 'version', 'records', 'cursor', 'network_fallback' ); if ( 1 !== ( $raw_ledger['version'] ?? null ) || array_diff( array_keys( $raw_ledger ), $allowed_ledger_keys ) || ! array_key_exists( 'records', $raw_ledger ) || ! array_key_exists( 'cursor', $raw_ledger ) || ! array_key_exists( 'network_fallback', $raw_ledger ) ) { return null; } $records = ai4seo_normalize_third_party_seo_metadata_finalization_retry_record_collection( $raw_ledger['records'] ); $cursor = $raw_ledger['cursor']; $network_fallback = $raw_ledger['network_fallback']; if ( null === $records || ! is_string( $cursor ) || ( '' !== $cursor && 1 !== preg_match( '/\A[a-f0-9]{64}\z/', $cursor ) ) || ! is_array( $network_fallback ) || array_keys( $network_fallback ) !== array( 'active_token', 'restart_token', 'last_blog_id' ) || ! ai4seo_is_valid_third_party_seo_metadata_finalization_retry_token( $network_fallback['active_token'] ?? null, true ) || ! ai4seo_is_valid_third_party_seo_metadata_finalization_retry_token( $network_fallback['restart_token'] ?? null, true ) || ! is_int( $network_fallback['last_blog_id'] ?? null ) || $network_fallback['last_blog_id'] < 0 ) { return null; } if ( '' === $network_fallback['active_token'] && ( '' !== $network_fallback['restart_token'] || 0 !== $network_fallback['last_blog_id'] ) ) { return null; } return array( 'version' => 1, 'records' => $records, 'cursor' => $cursor, 'network_fallback' => $network_fallback, ); } /** * Preserves the public record-normalization contract while accepting the versioned ledger envelope. * * @param mixed $raw_ledger Stored option value. * @return array|null Normalized origin records, or null for invalid storage. */ function ai4seo_normalize_third_party_seo_metadata_finalization_retry_records( $raw_ledger ): ?array { $ledger = ai4seo_normalize_third_party_seo_metadata_finalization_retry_ledger( $raw_ledger ); return null === $ledger ? null : $ledger['records']; } /** * Reads the current verified site's complete durable third-party finalization ledger. * * @param bool|null $read_succeeded Receives whether authoritative storage was valid and readable. * @return array Normalized ledger, or the empty shape on failure. */ function ai4seo_read_third_party_seo_metadata_finalization_retry_ledger( ?bool &$read_succeeded = null ): array { $read_succeeded = false; $option_name = ai4seo_get_third_party_seo_metadata_finalization_retry_option_name(); $snapshot = ai4seo_get_raw_option_snapshot( $option_name ); $empty_ledger = ai4seo_get_empty_third_party_seo_metadata_finalization_retry_ledger(); if ( null === $snapshot ) { return $empty_ledger; } $ledger = ai4seo_normalize_third_party_seo_metadata_finalization_retry_ledger( $snapshot['exists'] ? $snapshot['value'] : null ); if ( null === $ledger ) { return $empty_ledger; } $read_succeeded = true; return $ledger; } /** * Reads the current verified site's durable third-party finalization origin records. * * @param bool|null $read_succeeded Receives whether authoritative storage was valid and readable. * @return array Normalized origin records keyed by scope. */ function ai4seo_read_third_party_seo_metadata_finalization_retry_records( ?bool &$read_succeeded = null ): array { $ledger = ai4seo_read_third_party_seo_metadata_finalization_retry_ledger( $read_succeeded ); return $read_succeeded ? $ledger['records'] : array(); } /** * Adds one constant-size all-sites fallback generation to a normalized ledger. * * New work arriving during an active sweep requests one later full sweep without rewinding * the active cursor, so permanently failing early sites cannot starve later blog IDs. * * @param array $ledger Normalized ledger, mutated in place. * @return string Active or pending token that durably represents the new work. */ function ai4seo_add_third_party_seo_metadata_network_fallback_generation( array &$ledger ): string { $retry_token = function_exists( 'wp_generate_uuid4' ) ? wp_generate_uuid4() : uniqid( 'ai4seo_', true ); $network_fallback = $ledger['network_fallback']; if ( '' === $network_fallback['active_token'] ) { $network_fallback['active_token'] = $retry_token; $network_fallback['restart_token'] = ''; $network_fallback['last_blog_id'] = 0; } else { // Replacing the single pending token lets a page claim clear only its own safety token; // every later arrival remains distinguishable while storage stays constant-size. $network_fallback['restart_token'] = $retry_token; } $ledger['network_fallback'] = $network_fallback; return $retry_token; } /** * Persist one bounded all-sites fallback generation. * * @param string|null $owned_token Receives the durable active or pending generation token. * @return bool Whether the fallback generation was written or already represented durably. */ function ai4seo_require_third_party_seo_metadata_network_fallback( ?string &$owned_token = null ): bool { $owned_token = null; $option_name = ai4seo_get_third_party_seo_metadata_finalization_retry_option_name(); $attempt_limit = ai4seo_get_post_id_option_mutation_attempt_limit(); for ( $attempt = 0; $attempt < $attempt_limit; ++$attempt ) { $snapshot = ai4seo_get_raw_option_snapshot( $option_name ); if ( null === $snapshot ) { return false; } $ledger = ai4seo_normalize_third_party_seo_metadata_finalization_retry_ledger( $snapshot['exists'] ? $snapshot['value'] : null ); if ( null === $ledger ) { return false; } $original_ledger = $ledger; $owned_token = ai4seo_add_third_party_seo_metadata_network_fallback_generation( $ledger ); $is_envelope = $snapshot['exists'] && is_array( $snapshot['value'] ) && 1 === ( $snapshot['value']['version'] ?? null ); if ( $is_envelope && $ledger === $original_ledger ) { return true; } $compare_and_swap_result = ai4seo_compare_and_swap_option_snapshot( $option_name, $snapshot, $ledger, false ); if ( null === $compare_and_swap_result ) { return false; } if ( ! $compare_and_swap_result ) { continue; } $verified_ledger = ai4seo_read_third_party_seo_metadata_finalization_retry_ledger( $read_succeeded ); if ( ! $read_succeeded ) { return false; } return $owned_token === $verified_ledger['network_fallback']['active_token'] || $owned_token === $verified_ledger['network_fallback']['restart_token']; } return false; } /** * Adds bounded post retry ownership to the current verified site's durable ledger. * * @param array $site_state Origin site identity. * @param array $post_ids Post IDs requiring durable finalization retry. * @param array $owned_retry_record Receives exact post tokens or the full-rebuild token owned by this finalizer. * @param bool $advance_existing_ownership Whether a semantic new arrival must replace matching older tokens. * @return bool Whether bounded durable ownership was written or observed and verified. */ function ai4seo_add_third_party_seo_metadata_finalization_retry_record( array $site_state, array $post_ids, array &$owned_retry_record, bool $advance_existing_ownership = false ): bool { $owned_retry_record = array( 'post_id_tokens' => array(), 'requires_full_rebuild' => '', 'network_full_rebuild' => '', ); $scope_key = ai4seo_get_third_party_seo_metadata_finalization_retry_scope_key( $site_state ); $post_ids = array_values( array_unique( array_filter( array_map( 'absint', $post_ids ) ) ) ); $requires_full_rebuild = ! empty( $site_state['requires_full_rebuild'] ); if ( '' === $scope_key || ( ! $post_ids && ! $requires_full_rebuild ) ) { return false; } $retry_token = function_exists( 'wp_generate_uuid4' ) ? wp_generate_uuid4() : uniqid( 'ai4seo_', true ); $option_name = ai4seo_get_third_party_seo_metadata_finalization_retry_option_name(); $attempt_limit = ai4seo_get_post_id_option_mutation_attempt_limit(); for ( $attempt = 0; $attempt < $attempt_limit; ++$attempt ) { $snapshot = ai4seo_get_raw_option_snapshot( $option_name ); if ( null === $snapshot ) { return false; } $ledger = ai4seo_normalize_third_party_seo_metadata_finalization_retry_ledger( $snapshot['exists'] ? $snapshot['value'] : null ); if ( null === $ledger ) { return false; } $records = $ledger['records']; $is_envelope = $snapshot['exists'] && is_array( $snapshot['value'] ) && 1 === ( $snapshot['value']['version'] ?? null ); if ( ! isset( $records[ $scope_key ] ) && count( $records ) >= ai4seo_get_third_party_seo_metadata_finalization_retry_scope_limit() ) { $network_token = ai4seo_add_third_party_seo_metadata_network_fallback_generation( $ledger ); $compare_and_swap_result = ai4seo_compare_and_swap_option_snapshot( $option_name, $snapshot, $ledger, false ); if ( null === $compare_and_swap_result ) { return false; } if ( ! $compare_and_swap_result ) { continue; } $verified_ledger = ai4seo_read_third_party_seo_metadata_finalization_retry_ledger( $read_succeeded ); if ( ! $read_succeeded || ( $network_token !== $verified_ledger['network_fallback']['active_token'] && $network_token !== $verified_ledger['network_fallback']['restart_token'] ) ) { return false; } $owned_retry_record['network_full_rebuild'] = $network_token; return true; } $record = $records[ $scope_key ] ?? array( 'blog_id' => absint( $site_state['blog_id'] ?? 0 ), 'options_table' => isset( $site_state['options_table'] ) ? (string) $site_state['options_table'] : '', 'postmeta_table' => isset( $site_state['postmeta_table'] ) ? (string) $site_state['postmeta_table'] : '', 'post_id_tokens' => array(), 'requires_full_rebuild' => '', ); $record_was_changed = false; if ( ai4seo_get_third_party_seo_metadata_finalization_retry_scope_key( $record ) !== $scope_key ) { return false; } if ( '' !== $record['requires_full_rebuild'] && $advance_existing_ownership ) { // A new semantic arrival must outlive cleanup owned by a previously claimed full generation. $record['requires_full_rebuild'] = $retry_token; $record_was_changed = true; } elseif ( '' !== $record['requires_full_rebuild'] ) { $retry_token = $record['requires_full_rebuild']; $owned_retry_record['requires_full_rebuild'] = $record['requires_full_rebuild']; } elseif ( $requires_full_rebuild ) { $record['post_id_tokens'] = array(); $record['requires_full_rebuild'] = $retry_token; $record_was_changed = true; } else { foreach ( $post_ids as $post_id ) { if ( $advance_existing_ownership || ! isset( $record['post_id_tokens'][ $post_id ] ) ) { $record['post_id_tokens'][ $post_id ] = $retry_token; $record_was_changed = true; } } if ( count( $record['post_id_tokens'] ) > ai4seo_get_third_party_seo_metadata_finalization_retry_post_id_limit() ) { $record['post_id_tokens'] = array(); $record['requires_full_rebuild'] = $retry_token; $record_was_changed = true; } } if ( ! $record_was_changed && $is_envelope ) { if ( '' !== $record['requires_full_rebuild'] ) { return true; } foreach ( $post_ids as $post_id ) { $owned_retry_record['post_id_tokens'][ $post_id ] = $record['post_id_tokens'][ $post_id ]; } return true; } ksort( $record['post_id_tokens'], SORT_NUMERIC ); $records[ $scope_key ] = $record; ksort( $records, SORT_STRING ); $ledger['records'] = $records; $compare_and_swap_result = ai4seo_compare_and_swap_option_snapshot( $option_name, $snapshot, $ledger, false ); if ( null === $compare_and_swap_result ) { return false; } if ( ! $compare_and_swap_result ) { continue; } $verified_ledger = ai4seo_read_third_party_seo_metadata_finalization_retry_ledger( $read_succeeded ); $verified_records = $verified_ledger['records']; if ( ! $read_succeeded || ! isset( $verified_records[ $scope_key ] ) ) { return false; } if ( '' !== $record['requires_full_rebuild'] ) { if ( $verified_records[ $scope_key ]['requires_full_rebuild'] !== $retry_token || $verified_records[ $scope_key ]['post_id_tokens'] ) { return false; } $owned_retry_record['requires_full_rebuild'] = $retry_token; return true; } foreach ( $post_ids as $post_id ) { $verified_retry_token = $verified_records[ $scope_key ]['post_id_tokens'][ $post_id ] ?? ''; if ( '' === $verified_retry_token || $verified_retry_token !== $record['post_id_tokens'][ $post_id ] ) { return false; } $owned_retry_record['post_id_tokens'][ $post_id ] = $verified_retry_token; } return true; } return false; } /** * Removes only the exact durable retry tokens completed by this finalizer. * * @param array $site_state Origin site identity. * @param array $owned_retry_record Exact post tokens and optional full-rebuild token to remove. * @return bool Whether all exact owned tokens were absent after bounded CAS. */ function ai4seo_remove_third_party_seo_metadata_finalization_retry_record( array $site_state, array $owned_retry_record ): bool { $scope_key = ai4seo_get_third_party_seo_metadata_finalization_retry_scope_key( $site_state ); $owned_post_tokens = isset( $owned_retry_record['post_id_tokens'] ) && is_array( $owned_retry_record['post_id_tokens'] ) ? $owned_retry_record['post_id_tokens'] : array(); $owned_rebuild_token = isset( $owned_retry_record['requires_full_rebuild'] ) && is_string( $owned_retry_record['requires_full_rebuild'] ) ? $owned_retry_record['requires_full_rebuild'] : ''; if ( '' === $scope_key || ( ! $owned_post_tokens && '' === $owned_rebuild_token ) ) { return false; } $option_name = ai4seo_get_third_party_seo_metadata_finalization_retry_option_name(); $attempt_limit = ai4seo_get_post_id_option_mutation_attempt_limit(); for ( $attempt = 0; $attempt < $attempt_limit; ++$attempt ) { $snapshot = ai4seo_get_raw_option_snapshot( $option_name ); if ( null === $snapshot ) { return false; } $ledger = ai4seo_normalize_third_party_seo_metadata_finalization_retry_ledger( $snapshot['exists'] ? $snapshot['value'] : null ); if ( null === $ledger ) { return false; } $records = $ledger['records']; $is_envelope = $snapshot['exists'] && is_array( $snapshot['value'] ) && 1 === ( $snapshot['value']['version'] ?? null ); $did_remove_owned_token = false; foreach ( $owned_post_tokens as $post_id => $retry_token ) { $post_id = absint( $post_id ); if ( isset( $records[ $scope_key ]['post_id_tokens'][ $post_id ] ) && $records[ $scope_key ]['post_id_tokens'][ $post_id ] === $retry_token ) { unset( $records[ $scope_key ]['post_id_tokens'][ $post_id ] ); $did_remove_owned_token = true; } } if ( '' !== $owned_rebuild_token && isset( $records[ $scope_key ]['requires_full_rebuild'] ) && $records[ $scope_key ]['requires_full_rebuild'] === $owned_rebuild_token ) { $records[ $scope_key ]['requires_full_rebuild'] = ''; $did_remove_owned_token = true; } if ( ! $did_remove_owned_token && $is_envelope ) { return true; } if ( isset( $records[ $scope_key ] ) && ! $records[ $scope_key ]['post_id_tokens'] && '' === $records[ $scope_key ]['requires_full_rebuild'] ) { unset( $records[ $scope_key ] ); } ksort( $records, SORT_STRING ); $ledger['records'] = $records; $compare_and_swap_result = ai4seo_compare_and_swap_option_snapshot( $option_name, $snapshot, $ledger, false ); if ( null === $compare_and_swap_result ) { return false; } if ( ! $compare_and_swap_result ) { continue; } $verified_ledger = ai4seo_read_third_party_seo_metadata_finalization_retry_ledger( $read_succeeded ); $verified_records = $verified_ledger['records']; if ( ! $read_succeeded ) { return false; } foreach ( $owned_post_tokens as $post_id => $retry_token ) { $post_id = absint( $post_id ); if ( isset( $verified_records[ $scope_key ]['post_id_tokens'][ $post_id ] ) && $verified_records[ $scope_key ]['post_id_tokens'][ $post_id ] === $retry_token ) { return false; } } if ( '' !== $owned_rebuild_token && isset( $verified_records[ $scope_key ]['requires_full_rebuild'] ) && $verified_records[ $scope_key ]['requires_full_rebuild'] === $owned_rebuild_token ) { return false; } return true; } return false; } /** * Selects the next deterministic non-wrapping exact-origin batch after a durable cursor. * * The following invocation wraps to the first key only after the current suffix is exhausted, * so retained early failures cannot consume work slots before every later key is visited. * * @param array $records Normalized exact origin records. * @param string $cursor Last claimed scope key. * @param int $limit Maximum selected records. * @return array Selected records keyed by scope. */ function ai4seo_select_third_party_seo_metadata_finalization_retry_record_batch( array $records, string $cursor, int $limit ): array { if ( ! $records || $limit <= 0 ) { return array(); } ksort( $records, SORT_STRING ); $scope_keys = array_keys( $records ); $start_index = 0; $did_find = false; foreach ( $scope_keys as $index => $scope_key ) { if ( '' === $cursor || strcmp( $scope_key, $cursor ) > 0 ) { $start_index = $index; $did_find = true; break; } } if ( ! $did_find ) { $start_index = 0; } $selected_scope_keys = array_slice( $scope_keys, $start_index, $limit ); return array_intersect_key( $records, array_fill_keys( $selected_scope_keys, true ) ); } /** * Claims one bounded exact-origin batch by advancing the durable cursor before work starts. * * Exact records remain in storage until token-conditional completion, so advancing past a failed * record is safe and lets a later invocation reach every other retained origin before wrapping. * * @param bool|null $claim_succeeded Receives whether storage was valid and the cursor was claimed. * @param array|null $claimed_ledger Receives the normalized ledger observed after the claim. * @return array Claimed exact origin records keyed by scope. */ function ai4seo_claim_third_party_seo_metadata_finalization_retry_record_batch( ?bool &$claim_succeeded = null, ?array &$claimed_ledger = null ): array { $claim_succeeded = false; $claimed_ledger = null; $option_name = ai4seo_get_third_party_seo_metadata_finalization_retry_option_name(); $attempt_limit = ai4seo_get_post_id_option_mutation_attempt_limit(); $claim_limit = ai4seo_get_third_party_seo_metadata_finalization_recovery_claim_limit(); for ( $attempt = 0; $attempt < $attempt_limit; ++$attempt ) { $snapshot = ai4seo_get_raw_option_snapshot( $option_name ); if ( null === $snapshot ) { return array(); } $ledger = ai4seo_normalize_third_party_seo_metadata_finalization_retry_ledger( $snapshot['exists'] ? $snapshot['value'] : null ); if ( null === $ledger ) { return array(); } $selected_records = ai4seo_select_third_party_seo_metadata_finalization_retry_record_batch( $ledger['records'], $ledger['cursor'], $claim_limit ); $new_cursor = $selected_records ? (string) array_key_last( $selected_records ) : ''; $is_envelope = $snapshot['exists'] && is_array( $snapshot['value'] ) && 1 === ( $snapshot['value']['version'] ?? null ); if ( ! $snapshot['exists'] ) { // A verified missing row is the canonical empty state; do not recreate reset-owned storage on idle requests. $claim_succeeded = true; $claimed_ledger = $ledger; return array(); } if ( $is_envelope && $new_cursor === $ledger['cursor'] ) { $claim_succeeded = true; $claimed_ledger = $ledger; return $selected_records; } $ledger['cursor'] = $new_cursor; $compare_and_swap_result = ai4seo_compare_and_swap_option_snapshot( $option_name, $snapshot, $ledger, false ); if ( null === $compare_and_swap_result ) { return array(); } if ( ! $compare_and_swap_result ) { continue; } $claim_succeeded = true; $claimed_ledger = $ledger; return $selected_records; } return array(); } /** * Reads one strict keyset page of active multisite blog IDs for the global fallback sweep. * * @param int $last_blog_id Last claimed blog ID. * @param int $limit Maximum returned blog IDs. * @param bool|null $read_succeeded Receives whether the authoritative page was valid. * @param bool|null $has_more Receives whether another page follows this one. * @return array Strict ascending blog IDs. */ function ai4seo_read_third_party_seo_metadata_network_fallback_blog_id_page( int $last_blog_id, int $limit, ?bool &$read_succeeded = null, ?bool &$has_more = null ): array { global $wpdb; $read_succeeded = false; $has_more = false; $last_blog_id = max( 0, $last_blog_id ); $limit = max( 1, min( ai4seo_get_third_party_seo_metadata_finalization_recovery_claim_limit(), $limit ) ); if ( ! is_multisite() ) { $current_blog_id = absint( get_current_blog_id() ); if ( $current_blog_id <= 0 ) { return array(); } $read_succeeded = true; return $current_blog_id > $last_blog_id ? array( $current_blog_id ) : array(); } $page_limit = $limit + 1; $page_query = ai4seo_prepare_database_query( 'SELECT blog_id FROM {{blogs_table}} WHERE blog_id > {{last_blog_id}} AND spam = 0 AND deleted = 0 AND archived = 0 ORDER BY blog_id ASC LIMIT {{page_limit}}', array( 'blogs_table' => ai4seo_database_identifier_binding( 'table.blogs' ), 'last_blog_id' => ai4seo_database_scalar_binding( '%d', $last_blog_id ), 'page_limit' => ai4seo_database_scalar_binding( '%d', $page_limit ), ) ); if ( false === $page_query ) { return array(); } $wpdb->last_error = ''; // The typed compiler owns the network table and bounded keyset bindings; fallback progress cannot use caches. // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared,WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching $raw_blog_ids = $wpdb->get_col( $page_query ); if ( $wpdb->last_error || ! is_array( $raw_blog_ids ) || count( $raw_blog_ids ) > $page_limit ) { return array(); } $blog_ids = array(); $previous_blog_id = $last_blog_id; foreach ( $raw_blog_ids as $raw_blog_id ) { $blog_id = ai4seo_normalize_database_id( $raw_blog_id ); if ( false === $blog_id || $blog_id <= $previous_blog_id ) { return array(); } $blog_ids[] = $blog_id; $previous_blog_id = $blog_id; } $has_more = count( $blog_ids ) > $limit; $read_succeeded = true; return array_slice( $blog_ids, 0, $limit ); } /** * Claims a network-fallback page before switching sites. * * The cursor advances with one owned restart token. A page failure leaves that token in place, * while a successful page may clear only the exact safety token it created. * * @param string $active_token Active global generation. * @param int $expected_last_blog_id Cursor used to read the page. * @param int $claimed_last_blog_id Last blog ID in the selected page. * @param string $owned_safety_token Receives the page-owned restart token, when one was created. * @return bool Whether the exact active cursor was claimed. */ function ai4seo_claim_third_party_seo_metadata_network_fallback_page( string $active_token, int $expected_last_blog_id, int $claimed_last_blog_id, string &$owned_safety_token ): bool { $owned_safety_token = ''; if ( ! ai4seo_is_valid_third_party_seo_metadata_finalization_retry_token( $active_token ) || $expected_last_blog_id < 0 || $claimed_last_blog_id <= $expected_last_blog_id ) { return false; } $option_name = ai4seo_get_third_party_seo_metadata_finalization_retry_option_name(); $attempt_limit = ai4seo_get_post_id_option_mutation_attempt_limit(); for ( $attempt = 0; $attempt < $attempt_limit; ++$attempt ) { $snapshot = ai4seo_get_raw_option_snapshot( $option_name ); if ( null === $snapshot ) { return false; } $ledger = ai4seo_normalize_third_party_seo_metadata_finalization_retry_ledger( $snapshot['exists'] ? $snapshot['value'] : null ); if ( null === $ledger ) { return false; } $network_fallback = $ledger['network_fallback']; if ( $active_token !== $network_fallback['active_token'] || $expected_last_blog_id !== $network_fallback['last_blog_id'] ) { return false; } $page_safety_token = ''; if ( '' === $network_fallback['restart_token'] ) { $page_safety_token = function_exists( 'wp_generate_uuid4' ) ? wp_generate_uuid4() : uniqid( 'ai4seo_', true ); $network_fallback['restart_token'] = $page_safety_token; } $network_fallback['last_blog_id'] = $claimed_last_blog_id; $ledger['network_fallback'] = $network_fallback; $compare_and_swap_result = ai4seo_compare_and_swap_option_snapshot( $option_name, $snapshot, $ledger, false ); if ( null === $compare_and_swap_result ) { return false; } if ( ! $compare_and_swap_result ) { continue; } $owned_safety_token = $page_safety_token; return true; } return false; } /** * Commits one claimed network page without clearing any concurrent fallback generation. * * @param string $active_token Generation whose page was processed. * @param int $claimed_last_blog_id Claimed cursor. * @param string $owned_safety_token Exact page-owned restart token, or empty when pre-existing. * @param bool $page_succeeded Whether every site switch, identity, schedule, and restore succeeded. * @param bool $is_complete_page Whether no later blog ID existed in the keyset snapshot. * @return bool Whether progress was checked and committed safely. */ function ai4seo_complete_third_party_seo_metadata_network_fallback_page( string $active_token, int $claimed_last_blog_id, string $owned_safety_token, bool $page_succeeded, bool $is_complete_page ): bool { $option_name = ai4seo_get_third_party_seo_metadata_finalization_retry_option_name(); $attempt_limit = ai4seo_get_post_id_option_mutation_attempt_limit(); for ( $attempt = 0; $attempt < $attempt_limit; ++$attempt ) { $snapshot = ai4seo_get_raw_option_snapshot( $option_name ); if ( null === $snapshot ) { return false; } $ledger = ai4seo_normalize_third_party_seo_metadata_finalization_retry_ledger( $snapshot['exists'] ? $snapshot['value'] : null ); if ( null === $ledger ) { return false; } $network_fallback = $ledger['network_fallback']; $original_network_fallback = $network_fallback; if ( $active_token !== $network_fallback['active_token'] ) { // Another checked finalizer already completed or promoted this generation. return true; } if ( $claimed_last_blog_id !== $network_fallback['last_blog_id'] ) { // Another page advanced the same generation; its later cursor owns completion. return true; } if ( $page_succeeded && '' !== $owned_safety_token && $owned_safety_token === $network_fallback['restart_token'] ) { $network_fallback['restart_token'] = ''; } if ( ! $page_succeeded && '' === $network_fallback['restart_token'] ) { $network_fallback['restart_token'] = function_exists( 'wp_generate_uuid4' ) ? wp_generate_uuid4() : uniqid( 'ai4seo_', true ); } if ( $is_complete_page ) { if ( '' !== $network_fallback['restart_token'] ) { $network_fallback['active_token'] = $network_fallback['restart_token']; $network_fallback['restart_token'] = ''; $network_fallback['last_blog_id'] = 0; } else { $network_fallback = array( 'active_token' => '', 'restart_token' => '', 'last_blog_id' => 0, ); } } $ledger['network_fallback'] = $network_fallback; if ( $network_fallback === $original_network_fallback ) { // The page claim already durably retained this failure/restart state. return true; } $compare_and_swap_result = ai4seo_compare_and_swap_option_snapshot( $option_name, $snapshot, $ledger, false ); if ( null === $compare_and_swap_result ) { return false; } if ( $compare_and_swap_result ) { return true; } } return false; } /** * Processes one bounded keyset page of the all-sites full-rebuild fallback. * * @param array|null $observed_ledger Optional normalized ledger observed by the exact-record claim. * @throws RuntimeException When one target site cannot be entered or verified. * @return bool Whether the page was absent or its durable progress was committed safely. */ function ai4seo_process_third_party_seo_metadata_network_fallback_page( ?array $observed_ledger = null ): bool { $dispatcher_context = ai4seo_get_third_party_seo_metadata_finalization_site_context(); if ( null === $observed_ledger ) { $ledger = ai4seo_read_third_party_seo_metadata_finalization_retry_ledger( $read_succeeded ); } else { $ledger = ai4seo_normalize_third_party_seo_metadata_finalization_retry_ledger( $observed_ledger ); $read_succeeded = null !== $ledger; } if ( ! $read_succeeded ) { return false; } $network_fallback = $ledger['network_fallback']; $active_token = $network_fallback['active_token']; if ( '' === $active_token ) { return true; } $last_blog_id = $network_fallback['last_blog_id']; $blog_ids = ai4seo_read_third_party_seo_metadata_network_fallback_blog_id_page( $last_blog_id, ai4seo_get_third_party_seo_metadata_finalization_recovery_claim_limit(), $page_read_succeeded, $has_more ); if ( ! $page_read_succeeded ) { // A fresh pending generation distinguishes this failed pass from a later failure-free sweep. if ( ! ai4seo_require_third_party_seo_metadata_network_fallback( $failure_token ) ) { ai4seo_debug_message( 418620960, 'Could not retain the all-sites third-party finalization fallback after its keyset read failed.', true ); } return false; } if ( ! $blog_ids ) { return ai4seo_complete_third_party_seo_metadata_network_fallback_page( $active_token, $last_blog_id, '', true, true ); } $claimed_last_blog_id = (int) end( $blog_ids ); $owned_safety_token = ''; if ( ! ai4seo_claim_third_party_seo_metadata_network_fallback_page( $active_token, $last_blog_id, $claimed_last_blog_id, $owned_safety_token ) ) { return false; } $page_succeeded = true; foreach ( $blog_ids as $blog_id ) { $switched_site = false; $site_succeeded = false; try { if ( absint( get_current_blog_id() ) !== $blog_id ) { if ( ! is_multisite() || ! function_exists( 'switch_to_blog' ) || ! function_exists( 'restore_current_blog' ) ) { throw new RuntimeException( 'The target site cannot be entered from this request.' ); } $switched_site = true === switch_to_blog( $blog_id ); if ( ! $switched_site ) { throw new RuntimeException( 'The target site switch did not complete.' ); } } $origin_context = ai4seo_get_third_party_seo_metadata_finalization_site_context(); if ( $blog_id !== $origin_context['blog_id'] || '' === $origin_context['options_table'] || '' === $origin_context['postmeta_table'] ) { throw new RuntimeException( 'The target site identity could not be verified.' ); } $site_succeeded = ai4seo_schedule_generation_status_summary_rebuild(); } catch ( Throwable $throwable ) { ai4seo_debug_message( 418620961, 'Could not schedule an all-sites third-party finalization fallback: ' . $throwable->getMessage(), true ); } finally { if ( $switched_site ) { try { restore_current_blog(); } catch ( Throwable $throwable ) { ai4seo_debug_message( 418620962, 'Could not restore the dispatcher after an all-sites third-party finalization fallback: ' . $throwable->getMessage(), true ); } } $restore_succeeded = ai4seo_restore_third_party_seo_metadata_finalization_site_context( $dispatcher_context ); } if ( ! $restore_succeeded ) { // The page claim already advanced with a retained safety token before the ambiguous switch. ai4seo_debug_message( 418620963, 'The all-sites third-party finalization fallback stopped after an ambiguous site restoration.', true ); return false; } if ( ! $site_succeeded ) { $page_succeeded = false; } } return ai4seo_complete_third_party_seo_metadata_network_fallback_page( $active_token, $claimed_last_blog_id, $owned_safety_token, $page_succeeded, ! $has_more ); } /** * Requeues failed third-party synchronization finalization work for its originating site. * * @param array $site_state The consumed origin-site state. * @param array $post_ids Post IDs whose derived state still needs to be finalized. * @param bool $requires_full_rebuild Whether an origin-wide authoritative rebuild still needs scheduling. * @return void */ function ai4seo_requeue_third_party_seo_metadata_sync_site_state( array $site_state, array $post_ids, bool $requires_full_rebuild = false ): void { $post_ids = array_values( array_unique( array_filter( array_map( 'absint', $post_ids ) ) ) ); if ( ! $post_ids && ! $requires_full_rebuild ) { return; } // Requeue only unfinished IDs; completed IDs must stay consumed when one sibling fails. $site_state['changed_post_ids'] = array_fill_keys( $post_ids, true ); $site_state['requires_full_rebuild'] = $requires_full_rebuild; ai4seo_manage_third_party_seo_metadata_sync_request_state( 'requeue-site-state', 0, $site_state ); } /** * Durably owns one bounded finalization batch before any selected origin can change site context. * * Advancing ownership distinguishes a semantic new arrival from a previously claimed generation, * so cleanup by an older concurrent finalizer cannot consume the newer work through token reuse. * * @param array $site_states Selected origin states keyed by scope. * @param array $retry_storage_context Verified dispatcher storage context. * @param array $owned_retry_records_by_scope Durable ownership accumulated by this finalizer. * @param bool $advance_existing_ownership Whether every selected ID/full marker is a new generation. * @return bool Whether every selected unit of work has exact or global durable ownership. */ function ai4seo_preflight_third_party_seo_metadata_finalization_retry_ownership( array &$site_states, array $retry_storage_context, array &$owned_retry_records_by_scope, bool $advance_existing_ownership ): bool { if ( count( $site_states ) > ai4seo_get_third_party_seo_metadata_finalization_scope_work_limit() ) { return false; } foreach ( $site_states as &$site_state ) { if ( ! is_array( $site_state ) || ! ai4seo_is_third_party_seo_metadata_finalization_site_context_current( $retry_storage_context ) ) { return false; } $scope_key = ai4seo_get_third_party_seo_metadata_finalization_retry_scope_key( $site_state ); if ( '' === $scope_key ) { return false; } $changed_post_ids = isset( $site_state['changed_post_ids'] ) && is_array( $site_state['changed_post_ids'] ) ? array_keys( $site_state['changed_post_ids'] ) : array(); $retryable_post_ids = array(); foreach ( $changed_post_ids as $changed_post_id ) { $changed_post_id = absint( $changed_post_id ); if ( $changed_post_id > 0 && ! isset( $site_state['deleting_post_ids'][ $changed_post_id ] ) ) { $retryable_post_ids[] = $changed_post_id; } } $retryable_post_ids = array_values( array_unique( $retryable_post_ids ) ); $requires_full_rebuild = ! empty( $site_state['requires_full_rebuild'] ); if ( ! $retryable_post_ids && ! $requires_full_rebuild ) { continue; } $owned_retry_record = $owned_retry_records_by_scope[ $scope_key ] ?? array( 'post_id_tokens' => array(), 'requires_full_rebuild' => '', 'network_full_rebuild' => '', ); $owned_post_tokens = isset( $owned_retry_record['post_id_tokens'] ) && is_array( $owned_retry_record['post_id_tokens'] ) ? $owned_retry_record['post_id_tokens'] : array(); $owned_full_rebuild_token = isset( $owned_retry_record['requires_full_rebuild'] ) && is_string( $owned_retry_record['requires_full_rebuild'] ) ? $owned_retry_record['requires_full_rebuild'] : ''; if ( ! $advance_existing_ownership && '' !== $owned_full_rebuild_token ) { $site_state['requires_full_rebuild'] = true; continue; } $post_ids_requiring_ownership = $advance_existing_ownership ? $retryable_post_ids : array_values( array_diff( $retryable_post_ids, array_map( 'absint', array_keys( $owned_post_tokens ) ) ) ); $requires_owned_full_rebuild_token = $requires_full_rebuild && ( $advance_existing_ownership || '' === $owned_full_rebuild_token ); if ( ! $post_ids_requiring_ownership && ! $requires_owned_full_rebuild_token ) { continue; } $new_owned_retry_record = array(); if ( ! ai4seo_add_third_party_seo_metadata_finalization_retry_record( $site_state, $post_ids_requiring_ownership, $new_owned_retry_record, $advance_existing_ownership ) || ! ai4seo_is_third_party_seo_metadata_finalization_site_context_current( $retry_storage_context ) ) { return false; } if ( '' !== $new_owned_retry_record['requires_full_rebuild'] ) { $owned_retry_record = $new_owned_retry_record; $site_state['requires_full_rebuild'] = true; } elseif ( '' !== $new_owned_retry_record['network_full_rebuild'] ) { $owned_retry_record['network_full_rebuild'] = $new_owned_retry_record['network_full_rebuild']; } else { $owned_retry_record['post_id_tokens'] = array_replace( $owned_post_tokens, $new_owned_retry_record['post_id_tokens'] ); } $owned_retry_records_by_scope[ $scope_key ] = $owned_retry_record; } unset( $site_state ); return true; } /** * Captures the exact WordPress site-storage and multisite-switch context. * * @return array{blog_id: int, options_table: string, postmeta_table: string, switch_stack: array|null} */ function ai4seo_get_third_party_seo_metadata_finalization_site_context(): array { global $wpdb; $switch_stack = isset( $GLOBALS['_wp_switched_stack'] ) ? $GLOBALS['_wp_switched_stack'] : array(); return array( 'blog_id' => absint( get_current_blog_id() ), 'options_table' => isset( $wpdb->options ) ? (string) $wpdb->options : '', 'postmeta_table' => isset( $wpdb->postmeta ) ? (string) $wpdb->postmeta : '', 'switch_stack' => is_array( $switch_stack ) ? $switch_stack : null, ); } /** * Verifies the current WordPress site-storage and multisite-switch context. * * @param array $expected_context Previously captured context. * @return bool Whether the exact identity and switch stack are current. */ function ai4seo_is_third_party_seo_metadata_finalization_site_context_current( array $expected_context ): bool { if ( empty( $expected_context['blog_id'] ) || empty( $expected_context['options_table'] ) || empty( $expected_context['postmeta_table'] ) || ! isset( $expected_context['switch_stack'] ) || ! is_array( $expected_context['switch_stack'] ) ) { return false; } return ai4seo_get_third_party_seo_metadata_finalization_site_context() === $expected_context; } /** * Unwinds only switch frames added after a verified WordPress site context. * * The exact stack-prefix check prevents an ambiguous callback from popping a caller-owned frame. * Four attempts bound shutdown work while covering the expected single switch and limited nested * switches initiated by third-party callbacks. * * @param array $expected_context Previously captured context to restore. * @return bool Whether the exact identity and switch stack were restored. */ function ai4seo_restore_third_party_seo_metadata_finalization_site_context( array $expected_context ): bool { if ( ai4seo_is_third_party_seo_metadata_finalization_site_context_current( $expected_context ) ) { return true; } $expected_switch_stack = $expected_context['switch_stack'] ?? null; if ( ! is_array( $expected_switch_stack ) || ! function_exists( 'restore_current_blog' ) ) { return false; } $expected_stack_depth = count( $expected_switch_stack ); $restore_attempt_limit = 4; for ( $restore_attempt = 0; $restore_attempt < $restore_attempt_limit; ++$restore_attempt ) { $current_context = ai4seo_get_third_party_seo_metadata_finalization_site_context(); if ( ai4seo_is_third_party_seo_metadata_finalization_site_context_current( $expected_context ) ) { return true; } $current_switch_stack = $current_context['switch_stack']; if ( ! is_array( $current_switch_stack ) || count( $current_switch_stack ) <= $expected_stack_depth || array_slice( $current_switch_stack, 0, $expected_stack_depth ) !== $expected_switch_stack ) { return false; } try { restore_current_blog(); } catch ( Throwable $throwable ) { ai4seo_debug_message( 418620953, 'Could not unwind a partial third-party metadata finalization site switch: ' . $throwable->getMessage(), true ); } } return ai4seo_is_third_party_seo_metadata_finalization_site_context_current( $expected_context ); } /** * Refreshes derived state once for every post changed by persisted third-party synchronization. * * @return void */ function ai4seo_finalize_third_party_seo_metadata_sync(): void { global $wpdb; $retry_storage_context = ai4seo_get_third_party_seo_metadata_finalization_site_context(); $durable_retry_records = array(); $claimed_retry_ledger = null; // Claim before consuming request-local work, with one bounded retry for transient CAS contention. for ( $claim_pass = 1; $claim_pass <= 2; ++$claim_pass ) { $durable_retry_records = ai4seo_claim_third_party_seo_metadata_finalization_retry_record_batch( $retry_records_claim_succeeded, $claimed_retry_ledger ); if ( $retry_records_claim_succeeded ) { break; } } if ( ! $retry_records_claim_succeeded ) { ai4seo_debug_message( 418620949, 'Could not claim the bounded durable third-party metadata finalization retry batch.', true ); return; } if ( ! ai4seo_is_third_party_seo_metadata_finalization_site_context_current( $retry_storage_context ) ) { // Unexpected switch-stack or table identity must fail before request-local work is consumed. ai4seo_debug_message( 418620967, 'Third-party metadata finalization could not verify its retry-storage context before consuming request work.', true ); return; } $incoming_request_state = ai4seo_manage_third_party_seo_metadata_sync_request_state( 'consume-changed' ); $incoming_site_states = isset( $incoming_request_state['site_states'] ) && is_array( $incoming_request_state['site_states'] ) ? $incoming_request_state['site_states'] : array(); $incoming_requires_network_fallback = ! empty( $incoming_request_state['requires_network_fallback'] ); $owned_retry_records_by_scope = array(); $selected_scope_keys = array(); $selected_incoming_site_states = array(); $work_limit = ai4seo_get_third_party_seo_metadata_finalization_scope_work_limit(); foreach ( $durable_retry_records as $scope_key => $durable_retry_record ) { $durable_retry_site_state = array( 'blog_id' => $durable_retry_record['blog_id'], 'options_table' => $durable_retry_record['options_table'], 'postmeta_table' => $durable_retry_record['postmeta_table'], 'changed_post_ids' => array_fill_keys( array_keys( $durable_retry_record['post_id_tokens'] ), true ), 'requires_full_rebuild' => '' !== $durable_retry_record['requires_full_rebuild'], ); ai4seo_manage_third_party_seo_metadata_sync_request_state( 'requeue-site-state', 0, $durable_retry_site_state ); $selected_scope_keys[ $scope_key ] = true; $owned_retry_records_by_scope[ $scope_key ] = array( 'post_id_tokens' => $durable_retry_record['post_id_tokens'], 'requires_full_rebuild' => $durable_retry_record['requires_full_rebuild'], ); } $normalized_incoming_site_states = array(); $has_unselected_incoming_scope = $incoming_requires_network_fallback; foreach ( $incoming_site_states as $incoming_site_state ) { if ( ! is_array( $incoming_site_state ) ) { $has_unselected_incoming_scope = true; continue; } $scope_key = ai4seo_get_third_party_seo_metadata_finalization_retry_scope_key( $incoming_site_state ); if ( '' === $scope_key ) { $has_unselected_incoming_scope = true; continue; } $normalized_incoming_site_states[ $scope_key ] = $incoming_site_state; } ksort( $normalized_incoming_site_states, SORT_STRING ); foreach ( $normalized_incoming_site_states as $scope_key => $incoming_site_state ) { if ( isset( $selected_scope_keys[ $scope_key ] ) ) { $selected_incoming_site_states[ $scope_key ] = $incoming_site_state; continue; } if ( count( $selected_scope_keys ) < $work_limit ) { $selected_scope_keys[ $scope_key ] = true; $selected_incoming_site_states[ $scope_key ] = $incoming_site_state; continue; } $has_unselected_incoming_scope = true; } foreach ( $selected_incoming_site_states as $incoming_site_state ) { ai4seo_manage_third_party_seo_metadata_sync_request_state( 'requeue-site-state', 0, $incoming_site_state ); } if ( $has_unselected_incoming_scope && ! ai4seo_require_third_party_seo_metadata_network_fallback( $overflow_fallback_token ) ) { ai4seo_manage_third_party_seo_metadata_sync_request_state( 'requeue-network-fallback' ); ai4seo_debug_message( 418620964, 'Could not persist the bounded all-sites fallback for excess third-party finalization origins.', true ); return; } if ( ! ai4seo_preflight_third_party_seo_metadata_finalization_retry_ownership( $selected_incoming_site_states, $retry_storage_context, $owned_retry_records_by_scope, true ) ) { foreach ( $selected_incoming_site_states as $selected_incoming_site_state ) { ai4seo_manage_third_party_seo_metadata_sync_request_state( 'requeue-site-state', 0, $selected_incoming_site_state ); } $fallback_was_persisted = ai4seo_is_third_party_seo_metadata_finalization_site_context_current( $retry_storage_context ) && ai4seo_require_third_party_seo_metadata_network_fallback( $preflight_fallback_token ) && ai4seo_is_third_party_seo_metadata_finalization_site_context_current( $retry_storage_context ); if ( ! $fallback_was_persisted ) { ai4seo_manage_third_party_seo_metadata_sync_request_state( 'requeue-network-fallback' ); } ai4seo_debug_message( 418620968, 'Could not preflight durable ownership for every selected third-party metadata finalization origin.', true ); return; } // Requeue the preflight-normalized states so an exact overflow promoted to full is processed as its durable superset. foreach ( $selected_incoming_site_states as $selected_incoming_site_state ) { ai4seo_manage_third_party_seo_metadata_sync_request_state( 'requeue-site-state', 0, $selected_incoming_site_state ); } if ( ! ai4seo_process_third_party_seo_metadata_network_fallback_page( $claimed_retry_ledger ) ) { ai4seo_debug_message( 418620965, 'The bounded all-sites third-party metadata finalization fallback remains pending.', true ); } // One immediate retry absorbs transient table, switch, and coverage failures before shutdown returns. for ( $finalization_pass = 1; $finalization_pass <= 2; ++$finalization_pass ) { if ( ! ai4seo_is_third_party_seo_metadata_finalization_site_context_current( $retry_storage_context ) ) { ai4seo_debug_message( 418620954, 'Third-party metadata finalization stopped outside its verified retry-storage site context.', true ); return; } $request_state = ai4seo_manage_third_party_seo_metadata_sync_request_state( 'consume-changed' ); $site_states = isset( $request_state['site_states'] ) && is_array( $request_state['site_states'] ) ? $request_state['site_states'] : array(); $selected_pass_site_states = array(); $pass_requires_network_fallback = ! empty( $request_state['requires_network_fallback'] ); foreach ( $site_states as $site_state ) { if ( ! is_array( $site_state ) ) { $pass_requires_network_fallback = true; continue; } $scope_key = ai4seo_get_third_party_seo_metadata_finalization_retry_scope_key( $site_state ); if ( '' === $scope_key || ! isset( $selected_scope_keys[ $scope_key ] ) ) { $pass_requires_network_fallback = true; continue; } $selected_pass_site_states[ $scope_key ] = $site_state; } if ( $pass_requires_network_fallback && ! ai4seo_require_third_party_seo_metadata_network_fallback( $pass_fallback_token ) ) { foreach ( $selected_pass_site_states as $selected_pass_site_state ) { ai4seo_manage_third_party_seo_metadata_sync_request_state( 'requeue-site-state', 0, $selected_pass_site_state ); } ai4seo_manage_third_party_seo_metadata_sync_request_state( 'requeue-network-fallback' ); ai4seo_debug_message( 418620966, 'Could not retain the bounded all-sites fallback for third-party finalization work arriving during a finalization pass.', true ); return; } $site_states = $selected_pass_site_states; if ( ! $site_states ) { break; } if ( ! ai4seo_preflight_third_party_seo_metadata_finalization_retry_ownership( $site_states, $retry_storage_context, $owned_retry_records_by_scope, false ) ) { foreach ( $site_states as $selected_pass_site_state ) { ai4seo_manage_third_party_seo_metadata_sync_request_state( 'requeue-site-state', 0, $selected_pass_site_state ); } $fallback_was_persisted = ai4seo_is_third_party_seo_metadata_finalization_site_context_current( $retry_storage_context ) && ai4seo_require_third_party_seo_metadata_network_fallback( $pass_preflight_fallback_token ) && ai4seo_is_third_party_seo_metadata_finalization_site_context_current( $retry_storage_context ); if ( ! $fallback_was_persisted ) { ai4seo_manage_third_party_seo_metadata_sync_request_state( 'requeue-network-fallback' ); } ai4seo_debug_message( 418620969, 'Could not verify preflight ownership for the selected third-party metadata finalization pass.', true ); return; } // Every queued ID must be interpreted against the exact tables that owned the originating hook. foreach ( $site_states as $site_state ) { if ( ! is_array( $site_state ) ) { continue; } $origin_blog_id = absint( $site_state['blog_id'] ?? 0 ); $origin_options_table = isset( $site_state['options_table'] ) ? (string) $site_state['options_table'] : ''; $origin_postmeta_table = isset( $site_state['postmeta_table'] ) ? (string) $site_state['postmeta_table'] : ''; $changed_post_ids = isset( $site_state['changed_post_ids'] ) && is_array( $site_state['changed_post_ids'] ) ? array_keys( $site_state['changed_post_ids'] ) : array(); $requires_full_rebuild = ! empty( $site_state['requires_full_rebuild'] ); if ( $origin_blog_id <= 0 || '' === $origin_options_table || '' === $origin_postmeta_table || ( ! $changed_post_ids && ! $requires_full_rebuild ) ) { continue; } $retryable_post_ids = array(); foreach ( $changed_post_ids as $changed_post_id ) { $changed_post_id = absint( $changed_post_id ); if ( $changed_post_id > 0 && ! isset( $site_state['deleting_post_ids'][ $changed_post_id ] ) ) { $retryable_post_ids[] = $changed_post_id; } } $retryable_post_ids = array_values( array_unique( $retryable_post_ids ) ); if ( ! $retryable_post_ids && ! $requires_full_rebuild ) { continue; } $scope_key = ai4seo_get_third_party_seo_metadata_finalization_retry_scope_key( $site_state ); $owned_retry_record = $owned_retry_records_by_scope[ $scope_key ] ?? array( 'post_id_tokens' => array(), 'requires_full_rebuild' => '', ); $previous_site_context = ai4seo_get_third_party_seo_metadata_finalization_site_context(); $is_origin_site = $origin_blog_id === $previous_site_context['blog_id'] && $origin_options_table === $previous_site_context['options_table'] && $origin_postmeta_table === $previous_site_context['postmeta_table']; $switched_site = false; if ( ! $is_origin_site ) { if ( ! is_multisite() || ! function_exists( 'switch_to_blog' ) || ! function_exists( 'restore_current_blog' ) ) { ai4seo_debug_message( 418620938, 'Could not enter the originating site for third-party metadata synchronization finalization.', true ); ai4seo_requeue_third_party_seo_metadata_sync_site_state( $site_state, $retryable_post_ids, $requires_full_rebuild ); if ( 2 === $finalization_pass ) { ai4seo_debug_message( 418620947, 'Third-party metadata synchronization remained outside its originating site after the bounded shutdown retry.', true ); } continue; } try { $switched_site = true === switch_to_blog( $origin_blog_id ); } catch ( Throwable $throwable ) { ai4seo_debug_message( 418620943, 'Could not switch to the originating site for third-party metadata synchronization finalization: ' . $throwable->getMessage(), true ); ai4seo_requeue_third_party_seo_metadata_sync_site_state( $site_state, $retryable_post_ids, $requires_full_rebuild ); if ( ! ai4seo_restore_third_party_seo_metadata_finalization_site_context( $previous_site_context ) ) { ai4seo_debug_message( 418620955, 'Third-party metadata finalization stopped after an ambiguous originating-site switch failure.', true ); return; } continue; } if ( ! $switched_site ) { ai4seo_debug_message( 418620939, 'Could not switch to the originating site for third-party metadata synchronization finalization.', true ); ai4seo_requeue_third_party_seo_metadata_sync_site_state( $site_state, $retryable_post_ids, $requires_full_rebuild ); if ( ! ai4seo_restore_third_party_seo_metadata_finalization_site_context( $previous_site_context ) ) { ai4seo_debug_message( 418620955, 'Third-party metadata finalization stopped after an ambiguous originating-site switch result.', true ); return; } continue; } } $failed_post_ids = array(); $coverage_failed = false; $full_rebuild_was_scheduled = ! $requires_full_rebuild; $restore_was_verified = true; try { $is_verified_origin_site = absint( get_current_blog_id() ) === $origin_blog_id && ( isset( $wpdb->options ) ? (string) $wpdb->options : '' ) === $origin_options_table && ( isset( $wpdb->postmeta ) ? (string) $wpdb->postmeta : '' ) === $origin_postmeta_table; if ( ! $is_verified_origin_site ) { ai4seo_debug_message( 418620940, 'The originating site storage could not be verified before third-party metadata synchronization finalization.', true ); $failed_post_ids = $retryable_post_ids; } else { foreach ( $retryable_post_ids as $this_post_id ) { $coverage_was_refreshed = false; try { $coverage_was_refreshed = ai4seo_refresh_one_posts_metadata_coverage_status( $this_post_id ); } catch ( Throwable $throwable ) { ai4seo_debug_message( 418620944, 'Could not refresh metadata coverage after third-party metadata synchronization: ' . $throwable->getMessage(), true ); } if ( ! $coverage_was_refreshed ) { $failed_post_ids[] = $this_post_id; $coverage_failed = true; ai4seo_debug_message( 418620941, 'Could not refresh metadata coverage after third-party metadata synchronization.', true ); } try { ai4seo_purge_frontend_cache_for_post( $this_post_id ); } catch ( Throwable $throwable ) { // Cache integrations are best-effort and must not break request shutdown. ai4seo_debug_message( 418620937, 'Could not purge the frontend cache after third-party metadata synchronization: ' . $throwable->getMessage(), true ); } } $must_schedule_full_rebuild = $requires_full_rebuild || ( 2 === $finalization_pass && $coverage_failed ); if ( $must_schedule_full_rebuild ) { $rebuild_was_scheduled = false; try { $rebuild_was_scheduled = ai4seo_schedule_generation_status_summary_rebuild(); } catch ( Throwable $throwable ) { ai4seo_debug_message( 418620952, 'Could not schedule the authoritative third-party metadata finalization rebuild: ' . $throwable->getMessage(), true ); } if ( ! $rebuild_was_scheduled ) { ai4seo_debug_message( 418620948, 'Could not verify durable generation-summary rebuild scheduling after third-party metadata finalization failure.', true ); } if ( $requires_full_rebuild ) { $full_rebuild_was_scheduled = $rebuild_was_scheduled; } } } } finally { if ( $switched_site ) { try { restore_current_blog(); } catch ( Throwable $throwable ) { ai4seo_debug_message( 418620953, 'Could not restore the prior site after third-party metadata synchronization finalization: ' . $throwable->getMessage(), true ); } } $restore_was_verified = ai4seo_restore_third_party_seo_metadata_finalization_site_context( $previous_site_context ); if ( ! $restore_was_verified ) { ai4seo_debug_message( 418620942, 'Could not verify restoration of the prior site after third-party metadata synchronization finalization.', true ); } } // Failed restoration makes every operation's site ownership ambiguous, so retry the full origin batch. if ( ! $restore_was_verified ) { $failed_post_ids = $retryable_post_ids; } $full_rebuild_retry_required = $requires_full_rebuild && ( ! $full_rebuild_was_scheduled || ! $restore_was_verified ); if ( $requires_full_rebuild && $full_rebuild_was_scheduled && $restore_was_verified ) { // The verified full analysis is the durable superset repair for any direct per-post refresh failure. $failed_post_ids = array(); } ai4seo_requeue_third_party_seo_metadata_sync_site_state( $site_state, $failed_post_ids, $full_rebuild_retry_required ); if ( ! $restore_was_verified ) { // Every selected origin was preowned from the dispatcher; stop before using an ambiguous switch stack. return; } $completed_post_ids = array_values( array_diff( $retryable_post_ids, $failed_post_ids ) ); $completed_token_lookup = array_fill_keys( $completed_post_ids, true ); $completed_retry_record = array( 'post_id_tokens' => array_intersect_key( $owned_retry_record['post_id_tokens'], $completed_token_lookup ), 'requires_full_rebuild' => $full_rebuild_retry_required ? '' : $owned_retry_record['requires_full_rebuild'], ); $is_retry_storage_site = ai4seo_is_third_party_seo_metadata_finalization_site_context_current( $retry_storage_context ); if ( $completed_retry_record['post_id_tokens'] || '' !== $completed_retry_record['requires_full_rebuild'] ) { if ( ! $is_retry_storage_site || ! ai4seo_remove_third_party_seo_metadata_finalization_retry_record( $site_state, $completed_retry_record ) ) { // Leaving exact retry tokens is safer than acknowledging cleanup that could not be verified. ai4seo_debug_message( 418620951, 'Could not clear completed third-party metadata finalization retry ownership.', true ); } else { foreach ( array_keys( $completed_retry_record['post_id_tokens'] ) as $completed_post_id ) { unset( $owned_retry_records_by_scope[ $scope_key ]['post_id_tokens'][ $completed_post_id ] ); } if ( '' !== $completed_retry_record['requires_full_rebuild'] ) { $owned_retry_records_by_scope[ $scope_key ]['requires_full_rebuild'] = ''; } } } } } } /** * Normalizes a resolved provider value while retaining its caller-owned fallback. * * @param mixed $resolved_value The provider's replacement result. * @param string $fallback The original value to retain when replacement is not a string. * @param string $metadata_identifier The SOOZ metadata field whose length cap applies. * @return string The normalized result, or the unchanged fallback. */ function ai4seo_finish_resolved_metadata( $resolved_value, string $fallback, string $metadata_identifier ): string { if ( ! is_string( $resolved_value ) ) { return $fallback; } // Apply the field cap only after a provider successfully returns a string. $resolved_value = ai4seo_normalize_editor_input_value( $resolved_value ); $max_length = ai4seo_get_max_editor_input_length( $metadata_identifier ); return ai4seo_trim_string_to_length( $resolved_value, $max_length ); } /** * Resolves Yoast template variables in metadata that SOOZ is about to render on the frontend. * * @param string $metadata_value The raw metadata value. * @param int $post_id The post id used as Yoast replacement context. * @param string $metadata_identifier The SOOZ metadata identifier. * @return string The resolved metadata value, or the original value when resolution is unavailable. */ function ai4seo_resolve_yoast_metadata_variables( string $metadata_value, int $post_id, string $metadata_identifier ): string { // Most metadata is literal, so avoid loading Yoast context unless a template marker is present. if ( '' === $metadata_value || false === strpos( $metadata_value, '%%' ) ) { return $metadata_value; } // Share registry-derived field support with synchronization and the other integration resolvers. $yoast_metadata_identifiers = ai4seo_get_third_party_seo_plugin_generation_metadata_identifiers( AI4SEO_THIRD_PARTY_PLUGIN_YOAST_SEO ); // Resolve only Yoast-supported fields when its replacement service is available in this request. if ( ! in_array( $metadata_identifier, $yoast_metadata_identifiers, true ) || ! ai4seo_is_plugin_or_theme_active( AI4SEO_THIRD_PARTY_PLUGIN_YOAST_SEO ) || ! class_exists( 'WPSEO_Replace_Vars' ) ) { return $metadata_value; } // Supply the current post on every request so title, separator, and site-name variables remain dynamic. $post = get_post( $post_id ); if ( ! $post instanceof WP_Post ) { return $metadata_value; } // Preserve the raw template if Yoast cannot resolve it, matching the integration's fail-safe contract. try { $yoast_replace_vars = new WPSEO_Replace_Vars(); $resolved_value = $yoast_replace_vars->replace( $metadata_value, $post ); } catch ( Throwable $throwable ) { return $metadata_value; } return ai4seo_finish_resolved_metadata( $resolved_value, $metadata_value, $metadata_identifier ); } /** * Resolves SEOPress template variables in metadata used outside its own renderer. * * @param string $metadata_value The raw metadata value. * @param int $post_id The post id used as SEOPress replacement context. * @param string $metadata_identifier The SOOZ metadata identifier. * @return string The resolved metadata value, or the original value when resolution is unavailable. * @noinspection PhpUndefinedNamespaceInspection */ function ai4seo_resolve_seopress_metadata_variables( string $metadata_value, int $post_id, string $metadata_identifier ): string { // Literal values bypass SEOPress services on the common frontend path. if ( '' === $metadata_value || false === strpos( $metadata_value, '%%' ) ) { return $metadata_value; } // Share registry-derived field support with synchronization and the other integration resolvers. $seopress_metadata_identifiers = ai4seo_get_third_party_seo_plugin_generation_metadata_identifiers( AI4SEO_THIRD_PARTY_PLUGIN_SEOPRESS ); if ( ! in_array( $metadata_identifier, $seopress_metadata_identifiers, true ) || ! ai4seo_is_plugin_or_theme_active( AI4SEO_THIRD_PARTY_PLUGIN_SEOPRESS ) || ! function_exists( 'seopress_get_service' ) || ! class_exists( '\\SEOPress\\Services\\Context\\ContextPage' ) ) { return $metadata_value; } // Let another integration handle mixed or foreign templates instead of stripping unknown tags. if ( ! preg_match_all( '/%%(.*?)%%/u', $metadata_value, $matches ) || empty( $matches[1] ) ) { return $metadata_value; } try { $tags_to_string = seopress_get_service( 'TagsToString' ); if ( ! is_object( $tags_to_string ) || ! is_callable( array( $tags_to_string, 'getTagClass' ) ) || ! is_callable( array( $tags_to_string, 'replace' ) ) ) { return $metadata_value; } foreach ( array_unique( $matches[1] ) as $seopress_tag ) { if ( null === $tags_to_string->getTagClass( $seopress_tag ) ) { return $metadata_value; } } /* @noinspection PhpUndefinedClassInspection */ $context_page = new \SEOPress\Services\Context\ContextPage(); $context = $context_page->buildContextWithCurrentId( $post_id )->getContext(); $resolved_value = $tags_to_string->replace( $metadata_value, $context ); } catch ( Throwable $throwable ) { return $metadata_value; } return ai4seo_finish_resolved_metadata( $resolved_value, $metadata_value, $metadata_identifier ); } /** * Classifies single-percent metadata variables against Rank Math's live registry. * * @param string $metadata_value The metadata value to inspect. * @return array Registered and unregistered full variable tokens. */ function ai4seo_get_rank_math_metadata_variable_matches( string $metadata_value ): array { $variable_matches = array( 'registered' => array(), 'unregistered' => array(), ); // Avoid initializing Rank Math on the common literal-value path or when its registry is unavailable. if ( '' === $metadata_value || false === strpos( $metadata_value, '%' ) || ! function_exists( 'rank_math' ) ) { return $variable_matches; } try { $rank_math = rank_math(); if ( ! isset( $rank_math->variables ) ) { return $variable_matches; } // AJAX and CLI requests do not fire Rank Math's normal admin/frontend setup hooks. if ( is_callable( array( $rank_math->variables, 'setup' ) ) ) { $rank_math->variables->setup(); } if ( ! is_callable( array( $rank_math->variables, 'get_replacements' ) ) ) { return $variable_matches; } $registered_replacements = $rank_math->variables->get_replacements(); } catch ( Throwable $throwable ) { return $variable_matches; } if ( ! is_array( $registered_replacements ) || ! preg_match_all( '/(? $unregistered_token ) { $placeholder = '{' . $placeholder_base . $index . '}'; while ( false !== strpos( $metadata_value, $placeholder ) ) { $placeholder .= '_'; } $metadata_value = str_replace( $unregistered_token, $placeholder, $metadata_value ); $preserved_literals[ $placeholder ] = $unregistered_token; } $resolved_value = RankMath\Helper::replace_vars( $metadata_value, $post ); if ( $preserved_literals ) { $resolved_value = strtr( $resolved_value, $preserved_literals ); } } catch ( Throwable $throwable ) { return $original_metadata_value; } return ai4seo_finish_resolved_metadata( $resolved_value, $original_metadata_value, $metadata_identifier ); } /** * Resolves supported third-party templates and rejects values that remain unresolved. * * Returning an empty string lets frontend replace mode retain the integration's own correctly * rendered tag instead of publishing raw template syntax through SOOZ. * * @param string $metadata_value The raw metadata value. * @param int $post_id The post id used as replacement context. * @param string $metadata_identifier The SOOZ metadata identifier. * @return string The resolved metadata value, or an empty string when a template remains unresolved. */ function ai4seo_resolve_third_party_seo_metadata_variables( string $metadata_value, int $post_id, string $metadata_identifier ): string { // Apply each integration's syntax-specific resolver without affecting ordinary literal percentages. $metadata_value = ai4seo_resolve_seopress_metadata_variables( $metadata_value, $post_id, $metadata_identifier ); $metadata_value = ai4seo_resolve_yoast_metadata_variables( $metadata_value, $post_id, $metadata_identifier ); $metadata_value = ai4seo_resolve_rank_math_metadata_variables( $metadata_value, $post_id, $metadata_identifier ); // Never publish or forward a recognized token when its owning integration could not resolve it. if ( preg_match( '/%%[^%\s]+%%/u', $metadata_value ) || ai4seo_metadata_contains_rank_math_variable( $metadata_value ) ) { return ''; } return $metadata_value; } /** * Prepares optional third-party metadata context before it is sent for generation. * * @param string $metadata_value The submitted metadata value. * @param int $post_id The post id used as integration replacement context. * @param string $metadata_identifier The SOOZ metadata identifier. * @return string The resolved value, or an empty string when a supported token remains unresolved. */ function ai4seo_prepare_third_party_seo_metadata_value_for_generation_context( string $metadata_value, int $post_id, string $metadata_identifier ): string { // Literal context needs neither integration resolution nor a temporary WordPress filter. if ( '' === $metadata_value || ( false === strpos( $metadata_value, '%%' ) && ! ai4seo_metadata_contains_rank_math_variable( $metadata_value ) ) ) { return $metadata_value; } // Keep unresolved Yoast placeholders visible until the shared guard can reject the complete value. $preserve_unresolved_variables = static function (): bool { return false; }; $has_yoast_variable = false !== strpos( $metadata_value, '%%' ); if ( $has_yoast_variable ) { add_filter( 'wpseo_replacements_final', $preserve_unresolved_variables, PHP_INT_MAX ); } try { // Reuse frontend resolution while limiting Yoast placeholder preservation to this one call. $metadata_value = ai4seo_resolve_third_party_seo_metadata_variables( $metadata_value, $post_id, $metadata_identifier ); } finally { if ( $has_yoast_variable ) { remove_filter( 'wpseo_replacements_final', $preserve_unresolved_variables, PHP_INT_MAX ); } } return $metadata_value; } /** * Returns the keyphrase of the currently active third party SEO plugin, if it exists * * @param int $post_id The post id. * @return string The keyphrase or an empty string */ function ai4seo_get_any_third_party_seo_plugin_keyphrase( int $post_id ): string { if ( ai4seo_prevent_loops( __FUNCTION__ ) ) { ai4seo_debug_message( 608212638, 'Prevented loop', true ); return ''; } $active_supported_third_party_seo_plugins = ai4seo_get_active_third_party_seo_plugin_details(); foreach ( $active_supported_third_party_seo_plugins as $this_third_party_seo_plugin_identifier => $this_third_party_seo_plugin_details ) { if ( empty( $this_third_party_seo_plugin_details['generation-field-postmeta-keys'] ) || empty( $this_third_party_seo_plugin_details['generation-field-postmeta-keys']['focus-keyphrase'] ) ) { continue; } $keyphrase_postmeta_key = sanitize_text_field( $this_third_party_seo_plugin_details['generation-field-postmeta-keys']['focus-keyphrase'] ); $this_keyphrase = get_post_meta( $post_id, $keyphrase_postmeta_key, true ); if ( is_string( $this_keyphrase ) ) { $this_keyphrase = sanitize_text_field( $this_keyphrase ); if ( '' !== $this_keyphrase ) { return ai4seo_get_primary_third_party_seo_plugin_focus_keyphrase( $this_third_party_seo_plugin_identifier, $this_keyphrase ); } } } return ''; } /** * Prepares the shared exact-key postmeta value query used by provider readers. * * @param array $post_ids Normalized post IDs for one bounded query chunk. * @param string $meta_key Provider-owned postmeta key. * @return string|false Prepared query, or false when the typed specification is invalid. */ function ai4seo_prepare_third_party_postmeta_value_rows_query( array $post_ids, string $meta_key ) { return ai4seo_prepare_database_query( 'SELECT post_id, meta_value FROM {{postmeta_table}} WHERE meta_key = {{meta_key}} AND post_id IN ({{post_ids}})', array( 'postmeta_table' => ai4seo_database_identifier_binding( 'table.postmeta' ), // phpcs:ignore WordPress.DB.SlowDBQuery.slow_db_query_meta_key -- Each exact provider key is paired with one bounded post-ID chunk. 'meta_key' => ai4seo_database_scalar_binding( '%s', $meta_key ), 'post_ids' => ai4seo_database_list_binding( '%d', array_values( $post_ids ) ), ) ); } /** * Returns keyphrases for post IDs using active third-party SEO provider precedence. * * @param array $post_ids Post IDs. * @return array|null Keyphrases by post ID, or null on error. */ function ai4seo_read_third_party_seo_plugin_key_phrases( array $post_ids ): ?array { global $wpdb; if ( ai4seo_prevent_loops( __FUNCTION__ ) ) { ai4seo_debug_message( 807307700, 'Prevented loop', true ); return array(); } if ( ! $post_ids ) { return array(); } $sanitized_post_ids = array_values( array_filter( array_map( 'intval', $post_ids ) ) ); if ( empty( $sanitized_post_ids ) ) { return array(); } // Chunk post IDs to avoid oversized IN(...) clauses. $database_chunk_size = ai4seo_get_database_chunk_size(); $sanitized_post_ids_chunks = array_chunk( $sanitized_post_ids, $database_chunk_size ); // Provider order defines fallback precedence, so retain the active integration registry order. $active_supported_third_party_seo_plugins = ai4seo_get_active_third_party_seo_plugin_details(); if ( ! $active_supported_third_party_seo_plugins ) { return array(); } // Fill each post once so the first active provider with a non-empty keyphrase wins. $key_phrases = array(); foreach ( $active_supported_third_party_seo_plugins as $this_third_party_seo_plugin_identifier => $this_third_party_seo_plugin_details ) { if ( empty( $this_third_party_seo_plugin_details['generation-field-postmeta-keys'] ) || empty( $this_third_party_seo_plugin_details['generation-field-postmeta-keys']['focus-keyphrase'] ) ) { continue; } // Stop consulting lower-priority providers after every submitted post has a result. if ( count( $key_phrases ) === count( $post_ids ) ) { break; } $this_keyphrase_postmeta_key = sanitize_text_field( $this_third_party_seo_plugin_details['generation-field-postmeta-keys']['focus-keyphrase'] ); foreach ( $sanitized_post_ids_chunks as $this_post_ids_chunk ) { if ( empty( $this_post_ids_chunk ) ) { continue; } // Reuse the provider postmeta query contract so keyphrase and score readers bind chunks identically. $this_query = ai4seo_prepare_third_party_postmeta_value_rows_query( $this_post_ids_chunk, $this_keyphrase_postmeta_key ); if ( false === $this_query ) { return array(); } // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared,WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching -- The typed query compiler prepared the closed postmeta/key/ID spec; external SEO metadata needs a current batch read because provider writes have no reliable shared invalidation hook. $this_postmeta_entries = $wpdb->get_results( $this_query, ARRAY_A ); // Abort the complete provider fallback result rather than returning a partially filled map. if ( $wpdb->last_error ) { ai4seo_debug_message( 984321654, 'Database error: ' . $wpdb->last_error, true ); return array(); } if ( ! $this_postmeta_entries ) { continue; } // Resolve provider-specific compound formats before testing fallback precedence. foreach ( $this_postmeta_entries as $this_postmeta_entry ) { $this_post_id = isset( $this_postmeta_entry['post_id'] ) ? intval( $this_postmeta_entry['post_id'] ) : 0; $this_key_phrase_value = isset( $this_postmeta_entry['meta_value'] ) ? sanitize_text_field( $this_postmeta_entry['meta_value'] ) : ''; $this_key_phrase_value = ai4seo_get_primary_third_party_seo_plugin_focus_keyphrase( $this_third_party_seo_plugin_identifier, $this_key_phrase_value ); // Ignore malformed rows that cannot be associated with a submitted WordPress post. if ( ! $this_post_id ) { continue; } // Empty provider rows do not claim precedence; allow a later active integration to supply fallback. if ( '' === $this_key_phrase_value ) { continue; } // Preserve the first non-empty value supplied by the configured provider order. if ( isset( $key_phrases[ $this_post_id ] ) ) { continue; } $key_phrases[ $this_post_id ] = $this_key_phrase_value; } } } return $key_phrases; } /** * Returns Yoast SEO scores for the requested post IDs. * * @param array $post_ids Post IDs. * @return array|null Yoast SEO scores by post ID, or null on error. */ function ai4seo_read_yoast_seo_scores( array $post_ids ): ?array { global $wpdb; if ( ai4seo_prevent_loops( __FUNCTION__ ) ) { ai4seo_debug_message( 647946549, 'Prevented loop', true ); return array(); } // Avoid querying provider-owned metadata when Yoast is unavailable. if ( ! ai4seo_is_plugin_or_theme_active( AI4SEO_THIRD_PARTY_PLUGIN_YOAST_SEO ) ) { return array(); } if ( ! $post_ids ) { return array(); } // Normalize post IDs before binding them to the generated placeholders. $sanitized_post_ids = array_values( array_map( 'intval', $post_ids ) ); // Chunk post IDs to avoid oversized IN(...) clauses. $database_chunk_size = ai4seo_get_database_chunk_size(); $sanitized_post_id_chunks = array_chunk( $sanitized_post_ids, $database_chunk_size ); $yoast_seo_scores = array(); foreach ( $sanitized_post_id_chunks as $this_post_id_chunk ) { // Reuse the same exact-key query shape as other third-party postmeta readers. $this_query = ai4seo_prepare_third_party_postmeta_value_rows_query( $this_post_id_chunk, '_yoast_wpseo_linkdex' ); if ( false === $this_query ) { return array(); } // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared,WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching -- The typed query compiler prepared the closed postmeta/key/ID spec; Yoast scores need a current batch read because provider writes have no reliable shared invalidation hook. $this_chunk_yoast_seo_scores = $wpdb->get_results( $this_query ); // Abort the whole score map rather than exposing a partial set after a failed chunk. if ( $wpdb->last_error ) { ai4seo_debug_message( 984321655, 'Database error: ' . $wpdb->last_error, true ); return array(); } if ( ! $this_chunk_yoast_seo_scores ) { continue; } $yoast_seo_scores = array_merge( $yoast_seo_scores, $this_chunk_yoast_seo_scores ); } if ( ! $yoast_seo_scores ) { return array(); } // Convert raw provider rows to the function's established post-ID score map. $seo_scores = array(); foreach ( $yoast_seo_scores as $yoast_seo_score ) { $post_id = $yoast_seo_score->post_id; $seo_score = $yoast_seo_score->meta_value; // Ignore malformed provider rows that cannot be associated with a WordPress post. if ( ! is_numeric( $post_id ) || ! $post_id ) { continue; } // Preserve Yoast's raw score representation under its owning post ID. $seo_scores[ $post_id ] = $seo_score; } return $seo_scores; } // endregion // ___________________________________________________________________________________________.