includes/Integrations/class-builder-purge-watcher.php
Builder-purge watcher — purge stale page-builder CSS on builder updates.
Class Builder_Purge_Watcher
Purge builder + WPPO caches after a page-builder update.
class Builder_Purge_WatcherConstants
| Constant | Visibility | Value | Line |
|---|---|---|---|
NOTICE_TRANSIENT | public | \'wppo_builder_purge_notice\' | 41 |
DRIFT_PURGE_HOOK | public | \'wppo_builder_drift_purge\' | 56 |
DRIFT_PURGE_LOCK | public | \'wppo_builder_drift_purge_lock\' | 68 |
BUILDER_MAP | private | array( \'elementor\' => array( \'label\' => \'Elementor\', \'plugins\' => array( \'elementor/elementor.php\', \'elementor-pro/elementor-pro.php\' ), \'themes\' => array(), \'upload_subdirs\' => array( \'elementor/css\' ), \'content_subdirs\' => array(), \'clear_hooks\' => array( \'elementor/core/files/clear_cache\' ), ), \'divi\' => array( \'label\' => \'Divi\', \'plugins\' => array( \'divi-builder/divi-builder.php\' ), \'themes\' => array( \'Divi\' ), \'upload_subdirs\' => array(), \'content_subdirs\' => array( \'et-cache\' ), \'clear_hooks\' => array( \'et_core_cache_clear\' ), ), \'bricks\' => array( \'label\' => \'Bricks\', \'plugins\' => array(), \'themes\' => array( \'bricks\' ), \'upload_subdirs\' => array( \'bricks\' ), \'content_subdirs\' => array(), \'clear_hooks\' => array(), \'css_only\' => true, ), \'wpbakery\' => array( \'label\' => \'WPBakery\', \'plugins\' => array( \'js_composer/js_composer.php\' ), \'themes\' => array(), \'upload_subdirs\' => array( \'js_composer\' ), \'content_subdirs\' => array(), \'clear_hooks\' => array(), \'css_only\' => true, ), ) | 89 |
LAST_PURGE_OPTION | public | \'wppo_last_purge\' | 136 |
UPGRADE_PURGE_HOOK | public | \'wppo_upgrade_purge\' | 147 |
UPGRADE_PURGE_LOCK | public | \'wppo_upgrade_purge_lock\' | 160 |
BULK_REGEN_THRESHOLD | private | 5 | 269 |
Properties
| Property | Visibility | Type | Default | Line |
|---|---|---|---|---|
$upgrade_purged_hashes | private static | array | array() | 177 |
$resolved_builder_map_cache | private static | array | array() | 190 |
$drift_suspended | private static | bool | false | 203 |
$drift_handled_this_request | private static | bool | false | 215 |
$elementor_purged | private static | array | array() | 231 |
$shared_purge_cache | private static | mixed|null | null | 243 |
$bulk_regen_coalesced | private static | bool | false | 256 |
publicstatic reset_elementor_purge_memo()
public static function reset_elementor_purge_memo(): voidReset the Elementor per-request purge set (for tests).
Return: void.
publicstatic reset_drift_state()
public static function reset_drift_state(): voidReset the drift-signal per-request state (for tests).
Return: void.
publicstatic is_watcher_enabled()
public static function is_watcher_enabled(): boolWhether the builder purge watcher is enabled (issue #1288).
Return: bool — True when the watcher may run.
publicstatic is_drift_log_enabled()
public static function is_drift_log_enabled(): boolWhether drift-path activity-log entries are enabled (issue #1288).
Return: bool — True when drift purges should write a log entry.
privatestatic is_file_flag_enabled()
private static function is_file_flag_enabled(string $key): boolRead an additive file_optimisation flag, fail-open to true (issue #1288). Parameter Type Default Description $keystring— Flag key inside file_optimisation.
Return: bool — True when the flag is enabled or unreadable.
public register()
public function register(): voidRegister the upgrader hook plus builder-drift hooks.
Return: void.
public on_builder_drift()
public function on_builder_drift(): voidHandle Elementor asset-regen signals: defer the derived-cache purge.
Return: void.
protected schedule_deferred_drift_purge()
protected function schedule_deferred_drift_purge(): boolSchedule the heavy drift purge as a single background event.
Return: bool — True when a new event was enqueued. False when already pending (stays retryable) or on failure.
protected is_drift_purge_locked()
protected function is_drift_purge_locked(): boolWhether the drift-purge transient lock is currently held (issue #1288).
Return: bool — True when the drift-purge lock transient exists.
public run_deferred_drift_purge()
public function run_deferred_drift_purge(): voidBackground callback: run the heavy derived-cache purge.
Return: void.
public on_builder_drift_save()
public function on_builder_drift_save($post_id, $editor_data): voidHandle Elementor editor saves: requeue the saved post\’s used CSS. Parameter Type Default Description $post_idint— Post ID saved in the editor. $editor_datamixed— Editor data (unused).
Return: void.
public on_elementor_css_regen()
public function on_elementor_css_regen($css_file, =null $post_id): voidHandle Elementor per-post CSS regeneration (issue #1259). Parameter Type Default Description $css_filemixed— Elementor post CSS-file object or post ID. $post_id=null— Optional second action payload (post ID) when Elementor passes two args.
Return: void.
protected resolve_elementor_post_id()
protected function resolve_elementor_post_id($css_file, =null $post_id): intResolve an Elementor CSS-regen payload to a post ID (issue #1259). Parameter Type Default Description $css_filemixed— CSS-file object or post ID. $post_id=null— Optional second action payload (post ID fallback).
Return: int — Post ID, or 0 when unresolvable.
private coerce_post_id()
private function coerce_post_id($value): intCoerce a scalar payload to a post ID (issue #1259). Parameter Type Default Description $valuemixed— Raw payload.
Return: int — Post ID, or 0 when not a clean integer payload.
protected purge_post_static_cache()
protected function purge_post_static_cache(int $post_id, bool=true $bump_stats): voidPurge a single post\’s static HTML + derived CSS caches (issue #1259). Parameter Type Default Description $post_idint— Post ID whose cache must be purged. $bump_statsbool=true— Whether to bump dashboard stats. Bulk-regen callers pass false: the deferred full purge bumps once instead of N inline option writes.
Return: void.
protected requeue_used_css_for_elementor_post()
protected function requeue_used_css_for_elementor_post(int $post_id): boolRequeue Used-CSS for one Elementor post, coalesced for bulk regen (issue #1259). Parameter Type Default Description $post_idint— Post ID whose Used-CSS must be requeued.
Return: bool — True when a job was queued or already scheduled.
protected purge_post_url_caches()
protected function purge_post_url_caches(int $post_id): boolPurge page-cache + used-CSS sidecars for a single post URL (issue #1288). Parameter Type Default Description $post_idint— Post ID just saved in the builder.
Return: bool — True when a purge seam ran without throwing.
protected resolve_post_url_path()
protected function resolve_post_url_path(int $post_id): stringResolve a post ID to its cache URL path (issue #1288). Parameter Type Default Description $post_idint— Post ID.
Return: string — URL path (e.g. \’/my-page/\’) or \’\’ when unresolvable.
protected maybe_coalesce_bulk_regen()
protected function maybe_coalesce_bulk_regen(): voidSchedule the deferred full purge once bulk regen is detected (issue #1259).
Return: void.
protected write_drift_purge_log()
protected function write_drift_purge_log(bool=true $succeeded): voidLog a builder-drift purge outcome (issue #1288). Parameter Type Default Description $succeededbool=true— Whether the page-cache clear succeeded.
Return: void.
protected write_drift_save_log()
protected function write_drift_save_log(int $post_id, bool=true $purged, bool=true $queued): voidWrite the drift-save audit entry for an editor save (issue #1288). Parameter Type Default Description $post_idint— Post ID saved in the builder. $purgedbool=true— Whether the URL-scoped purge succeeded. $queuedbool=true— Whether regeneration was requeued.
Return: void.
publicstatic get_builder_map()
public static function get_builder_map(): arrayGet the builder map, filterable by hosts and themes.
Return: array<string,array> — Builder map keyed by builder slug.
public on_builder_update()
public function on_builder_update($upgrader, $hook_extra): voidHandle upgrader_process_complete: purge when a builder was updated. Parameter Type Default Description $upgradermixed— Upgrader instance (unused). $hook_extramixed— Update context (action/type/plugin/plugins/theme/themes).
Return: void.
private match_builders()
private function match_builders(array $plugins, array $themes, array $map): arrayIntersect updated plugin/theme slugs with the builder map. Parameter Type Default Description $pluginsarray— Updated plugin files. $themesarray— Updated theme slugs. $maparray— Builder map (resolved once per update).
Return: string[] — Matched builder keys.
protected collect_updated_slugs()
protected function collect_updated_slugs($hook_extra): arrayCollect updated plugin/theme slugs from an upgrader payload. Parameter Type Default Description $hook_extramixed— Update context.
Return: array{0:string[],1:string[]} — Tuple of (plugins, themes).
protected upgrade_payload_hash()
protected function upgrade_payload_hash($hook_extra): stringHash an upgrader payload for per-request dedupe. Parameter Type Default Description $hook_extramixed— Update context.
Return: string — Payload hash.
protected is_upgrade_purged()
protected function is_upgrade_purged($hook_extra): boolCheck whether this payload already purged this request. Parameter Type Default Description $hook_extramixed— Update context.
Return: bool — True when the payload hash was already recorded.
protected mark_upgrade_purged()
protected function mark_upgrade_purged($hook_extra): voidRecord a payload hash as purged for this request. Parameter Type Default Description $hook_extramixed— Update context.
Return: void.
protected purge_for_builders()
protected function purge_for_builders(array $matched, array $map): voidRun the purge chain for the matched builders. Parameter Type Default Description $matchedarray— Matched builder keys. $maparray— Builder map (resolved once per update).
Return: void.
public on_any_upgrade()
public function on_any_upgrade($upgrader, $hook_extra): voidHandle any plugin/theme/core update: auto-purge derived caches (issue #1276). Parameter Type Default Description $upgradermixed— Upgrader instance (unused). $hook_extramixed— Update context (action/type/plugin/plugins/theme/themes).
Return: void.
protected describe_upgrade()
protected function describe_upgrade(string $type, array $plugins, array $themes): stringDescribe an upgrade payload for logs + SPA last-purge reason. Parameter Type Default Description $typestring— Upgrade type (plugin/theme/core). $pluginsarray— Updated plugin files. $themesarray— Updated theme slugs.
Return: string — Human-readable description (bounded length).
protected schedule_deferred_upgrade_purge()
protected function schedule_deferred_upgrade_purge(string=\'\' $reason): boolSchedule the heavy generic-upgrade purge as a background event. Parameter Type Default Description $reasonstring=\'\'— Optional upgrade description (ignored, kept for backward compatibility).
Return: bool — True when an event was enqueued or already pending.
public run_deferred_upgrade_purge()
public function run_deferred_upgrade_purge(string=\'\' $reason): voidBackground callback: run the heavy generic-upgrade purge. Parameter Type Default Description $reasonstring=\'\'— Optional legacy upgrade description.
Return: void.
public purge_derived_caches()
public function purge_derived_caches(string=\'manual purge\' $reason): voidManual purge entry point for the SPA button + REST route (issue #1276). Parameter Type Default Description $reasonstring=\'manual purge\'— Human-readable reason stored for the SPA.
Return: void.
protected bump_combined_asset_versions()
protected function bump_combined_asset_versions(): voidInvalidate cached asset manifests/stats after a purge (issue #1276).
Return: void.
publicstatic get_last_purge()
public static function get_last_purge(): arrayGet the last derived-cache purge record for the SPA (issue #1276).
Return: array{reason:string,time:int} — Last-purge record.
protected record_last_purge()
protected function record_last_purge(string $reason): voidRecord the last derived-cache purge reason (issue #1276). Parameter Type Default Description $reasonstring— Human-readable purge reason.
Return: void.
publicstatic get_safe_preview_url()
public static function get_safe_preview_url(): stringSafe-mode preview URL that bypasses minify (issue #1276).
Return: string — Preview URL, or \’\’ when unresolvable.
protected purge_builder_directories()
protected function purge_builder_directories(array $matched, array $map): arrayDelete the matched builders\’ regenerable cache directories. Parameter Type Default Description $matchedarray— Matched builder keys. $maparray— Builder map.
Return: string[] — Deleted paths (for tests and logging).
private scoped_cache_dir()
private function scoped_cache_dir(string $base, $sub): stringResolve a builder cache subdirectory strictly inside its base dir. Parameter Type Default Description $basestring— Base directory (normalized). $submixed— Relative subdirectory from the map.
Return: string — Normalized absolute path, or \’\’ when unsafe.
private delete_css_files_only()
private function delete_css_files_only($fs, string $dir, array& $deleted): voidDelete only top-level *.css files inside a builder directory. Parameter Type Default Description $fsobject— WP_Filesystem instance. $dirstring— Scoped directory (already containment-checked). $deletedarray&— Deleted paths accumulator.
Return: void.
protected fire_builder_regeneration_hooks()
protected function fire_builder_regeneration_hooks(array $matched, array $map): voidFire builder-native cache-regeneration hooks (best-effort). Parameter Type Default Description $matchedarray— Matched builder keys. $maparray— Builder map.
Return: void.
protected purge_wppo_derived_caches()
protected function purge_wppo_derived_caches(): boolPurge WPPO\’s derived caches (page cache, used-CSS, critical-CSS).
Return: bool — True when the page-cache clear succeeded.
protected write_purge_log()
protected function write_purge_log(array $labels): voidWrite the audit-trail entry for a builder purge. Parameter Type Default Description $labelsarray— Human-readable builder names.
Return: void.
protected store_admin_notice()
protected function store_admin_notice(array $labels): voidStage the one-time admin success notice for the purge. Parameter Type Default Description $labelsarray— Human-readable builder names.
Return: void.
Hooks
Hooks referenced in includes/Integrations/class-builder-purge-watcher.php: Hook Type Line Notes wppo_builder_drift_requeueaction 460 — wppo_builder_drift_requeueaction 658 @param ×1 wppo_builder_purge_mapfilter 1126 @param ×1 wppo_after_builder_purgeaction 1343 @param ×1 wppo_after_upgrade_purgeaction 1464 @param ×1 wppo_builder_used_css_full_regenfilter 1980 @param ×1 wppo_builder_ccss_full_regenfilter 2031 @param ×1