| @@ -47,21 +47,20 @@ | ||
| 47 | 47 | * Detection is by constant and global only, never `is_plugin_active()` on a |
| 48 | 48 | * path string: a renamed plugin folder must not silently turn the integration |
| 49 | 49 | * off. Same rule as Render_Caches. |
| 50 | 50 | * |
| 51 | - * Deliberately purge-ALL only. Nginx Helper's per-URL entry point is a method | |
| 52 | - * call on its purger object rather than an action, and `Cache::purge_url()` | |
| 53 | - * has no action to hook yet; forwarding single URLs is a separate change once | |
| 54 | - * that seam lands. | |
| 51 | + * **This class is the mechanism, not the policy.** It knows how to detect the | |
| 52 | + * server cache and how to ask Nginx Helper to clear it. WHEN to ask is decided | |
| 53 | + * one level up, by `Server_Caches::forward()`, from the `intent` and `scope` | |
| 54 | + * on the purge-event contract — which is also where the reasoning for standing | |
| 55 | + * down on a content purge is written. Nothing here listens to a hook. | |
| 55 | 56 | * |
| 56 | - * **Converges with `Server_Caches` later.** PR #348 introduces that class for | |
| 57 | - * the same idea — forwarding a purge to a cache in front of PHP — with | |
| 58 | - * LiteSpeed as its first adapter and `xspeed_purge_server_caches` as its | |
| 59 | - * public seam. Nothing this class does overlaps with it today (different | |
| 60 | - * server cache, different plugin, and the purge sets are disjoint), so the two | |
| 61 | - * can land independently. Once #348 is merged, the right shape for this is an | |
| 62 | - * adapter registered on that filter rather than its own listener; keeping it | |
| 63 | - * separate now is what avoids editing a branch that is out for re-test. | |
| 57 | + * Purge-ALL only. Nginx Helper's per-URL entry point is | |
| 58 | + * `$GLOBALS['nginx_purger']->purge_url()`, a method on its purger object | |
| 59 | + * rather than an action, and it calls `is_page()`/`is_single()` internally — | |
| 60 | + * which emits `_doing_it_wrong` outside a main query, so WP-CLI, cron and REST | |
| 61 | + * purges would warn. The contract already carries the exact `urls`, so | |
| 62 | + * per-URL forwarding is a follow-up rather than a redesign. | |
| 64 | 63 | * |
| 65 | 64 | * **Multisite:** nginx keys one cache zone per *install*, not per subsite, so |
| 66 | 65 | * a purge here clears every site on the network at the nginx layer. That is |
| 67 | 66 | * accepted rather than worked around — a cold cache costs one slow request |
| @@ -84,59 +83,33 @@ | ||
| 84 | 83 | */ |
| 85 | 84 | private const NH_FASTCGI = 'enable_fastcgi'; |
| 86 | 85 | |
| 87 | 86 | /** |
| 88 | - * Re-entrancy latch. See purge_nginx_helper(). | |
| 87 | + * Forward a full purge to the server-level cache, when there is one. | |
| 89 | 88 | * |
| 90 | - * @var bool | |
| 91 | - */ | |
| 92 | - private static bool $purging = false; | |
| 93 | - | |
| 94 | - /** | |
| 95 | - * Register the listener. | |
| 89 | + * No gate on the purge's reason here — `Server_Caches::forward()` has | |
| 90 | + * already decided this purge should reach the server layer. Detection is | |
| 91 | + * still checked, because it is a fact about the environment rather than | |
| 92 | + * about the purge, and it is only stable at purge time: Nginx Helper | |
| 93 | + * builds `$GLOBALS['nginx_purger']` from its own `plugins_loaded` | |
| 94 | + * callback, so anything asked earlier races its load order. | |
| 96 | 95 | * |
| 97 | - * Registration is unconditional and the gate lives in the callback: this | |
| 98 | - * runs from `Plugin::init()` on `plugins_loaded`, and Nginx Helper builds | |
| 99 | - * `$GLOBALS['nginx_purger']` from its own `plugins_loaded` callback, so | |
| 100 | - * load order decides whether a check made here would see it. The callback | |
| 101 | - * runs during a purge, long after both plugins are up, where the answer | |
| 102 | - * is stable. | |
| 103 | - */ | |
| 104 | - public static function boot(): void { | |
| 105 | - add_action( 'xspeed_after_purge_all', array( __CLASS__, 'purge_nginx_helper' ), 10, 1 ); | |
| 106 | - } | |
| 107 | - | |
| 108 | - /** | |
| 109 | - * Forward a full purge to the server-level cache, when there is one. | |
| 96 | + * Re-entrancy is handled upstream. A third-party listener on | |
| 97 | + * `rt_nginx_helper_purge_all` that calls back into `Cache::purge_all()` | |
| 98 | + * used to recurse here until PHP ran out of stack, which is what the | |
| 99 | + * latch this method once carried was for. The inner purge now re-enters | |
| 100 | + * `Cache::dispatch_purge_event()`, whose `$purge_events_in_flight` guard | |
| 101 | + * is still held by the outer one and returns before any adapter runs. | |
| 102 | + * Pinned by a test that recurses through `Cache::purge_all()` itself | |
| 103 | + * rather than through this method. | |
| 110 | 104 | * |
| 111 | - * @param string $cause Who asked. Threaded through for symmetry with the | |
| 112 | - * other `xspeed_after_purge_all` listeners; Nginx | |
| 113 | - * Helper's action takes no arguments. | |
| 114 | 105 | * @return bool Whether the purge was forwarded. |
| 115 | 106 | */ |
| 116 | - public static function purge_nginx_helper( $cause = 'manual' ): bool { | |
| 117 | - unset( $cause ); | |
| 118 | - | |
| 119 | - /* | |
| 120 | - * Nginx Helper's purge is a directory sweep, but it is not OUR code: | |
| 121 | - * it runs third-party listeners on `rt_nginx_helper_purge_all`, and a | |
| 122 | - * site can easily have one that calls back into a WordPress purge — | |
| 123 | - * a "keep every cache in sync" mu-plugin is the common shape. Without | |
| 124 | - * this latch that lands back in Cache::purge_all(), which fires | |
| 125 | - * `xspeed_after_purge_all` again, and the two purges recurse until PHP | |
| 126 | - * runs out of stack. One forward per request is all this integration | |
| 127 | - * can usefully do anyway, since the second sweep would find an empty | |
| 128 | - * directory. | |
| 129 | - */ | |
| 130 | - if ( self::$purging ) { | |
| 131 | - return false; | |
| 132 | - } | |
| 133 | - | |
| 107 | + public static function purge_nginx_helper(): bool { | |
| 134 | 108 | if ( ! self::nginx_helper_is_fastcgi() ) { |
| 135 | 109 | return false; |
| 136 | 110 | } |
| 137 | 111 | |
| 138 | - self::$purging = true; | |
| 139 | 112 | try { |
| 140 | 113 | // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound -- Nginx Helper's own public integration hook; an xspeed_-prefixed name would reach nothing. |
| 141 | 114 | do_action( 'rt_nginx_helper_purge_all' ); |
| 142 | 115 | } catch ( \Throwable $e ) { |
| @@ -146,14 +119,14 @@ | ||
| 146 | 119 | * own. Letting it out would take down `Cache::purge_all()` — the |
| 147 | 120 | * admin presses Purge All, another plugin's mu-plugin fatals, and |
| 148 | 121 | * the failure reads as xSpeed's. The local sweep has already |
| 149 | 122 | * happened by the time we run, so swallowing this costs the |
| 150 | - * server layer and nothing else. `Server_Caches::forward()` on | |
| 151 | - * #348 catches at the same boundary for the same reason. | |
| 123 | + * server layer and nothing else. `Server_Caches::forward()` | |
| 124 | + * catches around this call for the same reason and logs it under | |
| 125 | + * WP_DEBUG; this inner catch is what turns a throw into an honest | |
| 126 | + * "not forwarded" return rather than a reported purge. | |
| 152 | 127 | */ |
| 153 | 128 | return false; |
| 154 | - } finally { | |
| 155 | - self::$purging = false; | |
| 156 | 129 | } |
| 157 | 130 | |
| 158 | 131 | return true; |
| 159 | 132 | } |
| @@ -199,9 +172,10 @@ | ||
| 199 | 172 | * has said "don't purge behind my back"; they have not said "ignore me |
| 200 | 173 | * when I press Purge All". Reading it as the latter would leave an |
| 201 | 174 | * explicit, operator-initiated purge silently short of the layer actually |
| 202 | 175 | * serving the page, which is the exact failure this integration exists to |
| 203 | - * fix. | |
| 176 | + * fix. `nginx_helper_purges_changes()` does read it, only to decide | |
| 177 | + * whether a content purge can be left to Nginx Helper. | |
| 204 | 178 | */ |
| 205 | 179 | public static function nginx_helper_is_fastcgi(): bool { |
| 206 | 180 | return null !== self::nginx_helper_cache_path(); |
| 207 | 181 | } |
| @@ -228,8 +202,23 @@ | ||
| 228 | 202 | if ( ! is_array( $options ) || self::NH_FASTCGI !== ( $options['cache_method'] ?? '' ) ) { |
| 229 | 203 | return null; |
| 230 | 204 | } |
| 231 | 205 | return $path; |
| 206 | + } | |
| 207 | + | |
| 208 | + /** | |
| 209 | + * Whether Nginx Helper purges changed pages by itself. | |
| 210 | + * | |
| 211 | + * Its `enable_purge` option is the one switch in front of all of its | |
| 212 | + * automatic purging: the post, comment and term hooks each return early | |
| 213 | + * without it. It defaults to off, so an install where the host never | |
| 214 | + * turned it on purges nothing when a post is published. Not part of the | |
| 215 | + * detection gate above; `Server_Caches` asks it only to decide whether a | |
| 216 | + * content purge can be left to Nginx Helper. | |
| 217 | + */ | |
| 218 | + public static function nginx_helper_purges_changes(): bool { | |
| 219 | + $options = get_site_option( self::NH_OPTION ); | |
| 220 | + return is_array( $options ) && ! empty( $options['enable_purge'] ); | |
| 232 | 221 | } |
| 233 | 222 | |
| 234 | 223 | /** |
| 235 | 224 | * The configured purge method (`unlink_files`, `get_request`, …), or '' |
