*/ private static $watched_toggles = []; /** * Whole options whose changes require a flush, mapped to the source * recorded with the request. * * @var array */ private static $watched_options = []; /** * Whether a flush was requested during the current request. When true, * maybe_flush() leaves the pending flush for the next request, whose * hooks reflect the new settings. * * @var bool */ private static $requested_this_request = false; /** * Register the pending-flush check. * * @return void */ public static function init(): void { add_action( 'wp_loaded', [ self::class, 'maybe_flush' ] ); } /** * Request a rewrite-rules flush on the next request. * * Each call stores a fresh token, so the stored value always changes and * maybe_flush()'s compare-and-swap can tell that a newer request arrived, * even when it comes from the same source. * * @param string $source Requesting module/feature ID, kept for debugging. * * @return void */ public static function request( string $source ): void { $sources = self::get_pending_sources(); if ( '' !== $source && ! in_array( $source, $sources, true ) ) { $sources[] = $source; } update_option( self::OPTION, [ 'sources' => $sources, 'token' => bin2hex( random_bytes( 8 ) ), ], true ); self::$requested_this_request = true; } /** * Request a flush whenever the given modules-option toggle changes value. * * Call this unconditionally (not only when the feature is enabled), since * switching the feature off must flush too. Safe to call repeatedly. * * @param string $toggle Toggle key in the modules option. * * @return void */ public static function watch_toggle( string $toggle ): void { if ( '' === $toggle ) { return; } if ( empty( self::$watched_toggles ) ) { add_action( 'update_option_' . self::MODULES_OPTION, [ self::class, 'on_modules_option_updated' ], 10, 2 ); add_action( 'add_option_' . self::MODULES_OPTION, [ self::class, 'on_modules_option_added' ], 10, 2 ); } self::$watched_toggles[ $toggle ] = true; } /** * Request a flush whenever the given option is added, updated or deleted. * * For options whose content shapes the rules (e.g. the stored custom post * type definitions). Hooking the option itself covers every write path: * settings screens, settings import, WP-CLI. `update_option()` fires no * hooks when the value is unchanged, so a no-op save does not flush. * * Call this unconditionally, whether or not the owning module is enabled. * Safe to call repeatedly. * * @param string $option Option name. * @param string $source Source recorded with the request; defaults to $option. * * @return void */ public static function watch_option( string $option, string $source = '' ): void { if ( '' === $option ) { return; } if ( ! isset( self::$watched_options[ $option ] ) ) { add_action( 'update_option_' . $option, [ self::class, 'on_watched_option_updated' ], 10, 3 ); add_action( 'add_option_' . $option, [ self::class, 'on_watched_option_added_or_deleted' ], 10, 1 ); add_action( 'delete_option_' . $option, [ self::class, 'on_watched_option_added_or_deleted' ], 10, 1 ); } self::$watched_options[ $option ] = '' !== $source ? $source : $option; } /** * `update_option_{option}` callback for watched options. * * @param mixed $old_value Previous value. * @param mixed $value New value. * @param string $option Option name. * * @return void */ public static function on_watched_option_updated( $old_value, $value, $option ): void { unset( $old_value, $value ); self::on_watched_option_added_or_deleted( $option ); } /** * `add_option_{option}` / `delete_option_{option}` callback for watched options. * * @param string $option Option name. * * @return void */ public static function on_watched_option_added_or_deleted( $option ): void { if ( is_string( $option ) && isset( self::$watched_options[ $option ] ) ) { self::request( self::$watched_options[ $option ] ); } } /** * `update_option_{modules}` callback: request a flush for each watched * toggle whose value changed. * * @param mixed $old_value Previous modules option value. * @param mixed $value New modules option value. * * @return void */ public static function on_modules_option_updated( $old_value, $value ): void { $old_value = is_array( $old_value ) ? $old_value : []; $value = is_array( $value ) ? $value : []; foreach ( array_keys( self::$watched_toggles ) as $toggle ) { if ( self::toggle_state( $old_value, $toggle ) !== self::toggle_state( $value, $toggle ) ) { self::request( $toggle ); } } } /** * `add_option_{modules}` callback: the first save of the modules option. * * @param string $option Option name. * @param mixed $value New modules option value. * * @return void */ public static function on_modules_option_added( $option, $value ): void { unset( $option ); self::on_modules_option_updated( [], $value ); } /** * `wp_loaded` callback: perform a pending flush, if any. * * The pending state is claimed (cleared) before flushing, so a flush that * fatals cannot repeat on every request. The claim is a compare-and-swap * against the value this request read: if another request changed the * option since (a newer request() whose settings this request's hooks do * not reflect, or a concurrent request that already claimed it), the * claim fails and this request leaves the flush to the next one. * * @return void */ public static function maybe_flush(): void { $stored = get_option( self::OPTION, null ); if ( null === $stored ) { // First run: create the option so later reads come from the // alloptions cache instead of a per-request lookup query. add_option( self::OPTION, [], '', true ); return; } if ( empty( $stored ) || self::$requested_this_request ) { return; } if ( ! self::claim( $stored ) ) { return; } flush_rewrite_rules( false ); } /** * Atomically reset the pending option to empty, but only if it still holds * the value this request read. * * @param mixed $stored Pending value as read by this request. * * @return bool Whether this request claimed the flush. */ private static function claim( $stored ): bool { global $wpdb; $claimed = $wpdb->update( $wpdb->options, [ 'option_value' => maybe_serialize( [] ) ], [ 'option_name' => self::OPTION, 'option_value' => maybe_serialize( $stored ), ] ); // The direct write bypasses the options API, and on a failed claim the // cached copy is stale anyway: drop both cached copies so later reads // in this request see the database value. Only runs while a flush is // pending, so the extra alloptions reload is rare. wp_cache_delete( 'alloptions', 'options' ); wp_cache_delete( self::OPTION, 'options' ); return 1 === $claimed; } /** * Plugin activation: request a flush so the first request with the plugin * loaded rebuilds the rules. While the plugin was inactive, WordPress * rebuilt them without its rules or filters (e.g. with core's `/random/` * rules even though disable_random_content is still stored as on), and no * toggle changes on reactivation to trigger a flush otherwise. * * @return void */ public static function on_activate(): void { self::request( 'activation' ); } /** * Plugin deactivation: drop the stored rules so WordPress rebuilds them * on the next request without this plugin's rules or filters. Flushing * here would rebuild with the plugin's hooks still loaded. * * @return void */ public static function on_deactivate(): void { delete_option( 'rewrite_rules' ); update_option( self::OPTION, [], true ); } /** * Sources (module/feature IDs) of the pending flush; empty when none. * * @return array */ public static function get_pending_sources(): array { $value = get_option( self::OPTION, [] ); $sources = is_array( $value ) && isset( $value['sources'] ) && is_array( $value['sources'] ) ? $value['sources'] : []; return array_values( array_filter( $sources, 'is_string' ) ); } /** * Whether a flush is pending. * * @return bool */ public static function is_pending(): bool { return ! empty( get_option( self::OPTION, [] ) ); } /** * A toggle's state in a modules-option value: null when the key is * absent (the registry then falls back to the module's fresh_default), * otherwise its boolean value, using Module_Registry's normalization. * Treating "absent" as distinct may cause one extra flush on a first * explicit save, but never a missed one. * * @param array $modules Modules option value. * @param string $toggle Toggle key. * * @return bool|null */ private static function toggle_state( array $modules, string $toggle ): ?bool { if ( ! array_key_exists( $toggle, $modules ) ) { return null; } $state = $modules[ $toggle ]; if ( null === $state || '' === $state || '0' === $state ) { return false; } return (bool) $state; } /** * Reset static state. For tests only. * * @return void */ public static function reset_for_tests(): void { self::$watched_toggles = []; self::$watched_options = []; self::$requested_this_request = false; } }