v2.1.1: Check for module presence

fix: Improve cache-purge module detection to prevent false positives

Author: lsthompson

CHANGELOG.md

@@ -1,6 +1,16 @@
 # Changelog
 All notable changes to TNC Toolbox for WordPress will be documented in this file.
 
+## [2.1.1] - 2026-01-10
+
+### 🐛 Bug Fix
+- **Cache Purge Detection**: Fix false positive module detection when `ea-nginx-cache-purge` is not installed
+  - Detection now requires specific response signatures from the cache-purge module
+  - Generic NGINX 301/404/405 responses no longer trigger false detection
+- **Detection Caching**: Fix stale detection cache preventing module discovery
+  - Settings page now always performs fresh detection check
+  - No HTTP requests on regular page loads (uses cached result)
+
 ## [2.1.0] - 2026-01-08
 
 ### 🚀 Feature

tnc-toolbox/core/settings.php

@@ -215,7 +215,7 @@ class="regular-text" />
                                     class="regular-text" />
                             </td>
                         </tr>
-                        <?php $status = TNC_Cache_Purge::get_status(); ?>
+                        <?php $status = TNC_Cache_Purge::get_status( true ); // Force recheck on settings page ?>
                         <tr>
                             <th scope="row">
                                 <label for="tnc_selective_purge">Selective Purging?</label>

tnc-toolbox/readme.txt

@@ -1,11 +1,11 @@
 === TNC Toolbox: Web Performance ===
 Author URI: https://tnc.works
 Plugin URI: https://merlot.digital
-Donate link: 
-Contributors: 
+Donate link:
+Contributors:
 Tags: NGINX, Cache Purge, Web Performance, Automatic Purge, Freeware
 Tested up to: 6.9
-Stable tag: 2.1.0
+Stable tag: 2.1.1
 License: GPLv3
 License URI: https://www.gnu.org/licenses/gpl-3.0.html
 
@@ -14,11 +14,11 @@ Designed for ea-NGINX (Cache/Proxy) on cPanel+WHM. Made to help you fly online!
 
 == Description ==
 
-TNC Toolbox aims to enhance your WordPress experience with NGINX-on-cPanel (ea-nginx). 
+TNC Toolbox aims to enhance your WordPress experience with NGINX-on-cPanel (ea-nginx).
 
 **Built for our Managed Server clients, we've open-sourced it so others can enjoy it too!**
 
-With a heavy focus on the Apache + NGINX as Reverse Caching Proxy web stack, the plugin aims to help with Website Management, Performance and Security. 
+With a heavy focus on the Apache + NGINX as Reverse Caching Proxy web stack, the plugin aims to help with Website Management, Performance and Security.
 
 > ❤️ **FOSS by [The Network Crew Pty Ltd](https://tnc.works) (TNC) for [Merlot Digital](https://merlot.digital) & the world.** ❤️
 
@@ -37,7 +37,7 @@ With a heavy focus on the Apache + NGINX as Reverse Caching Proxy web stack, the
 
 **Eager for even more capabilities?**
 
-We plan to add further features as clients & the community request it. 
+We plan to add further features as clients & the community request it.
 
 _Please let us know your ideas on [GitHub](https://github.com/The-Network-Crew/TNC-Toolbox-for-WordPress/) - we'd love to hear from you!_
 
@@ -152,6 +152,9 @@ _(* Change to main plugin file name may result in deactivation)_
 
 == Changelog ==
 
+= 2.1.1: Jan 10, 2026 =
+* Bug Fix: Fix false positive cache-purge module detection
+
 = 2.1.0: Jan 8, 2026 =
 * Feature: Selective Cache Purging with ea-nginx-cache-purge integration
 * Feature: "Purge This Page" button in admin bar when viewing posts

tnc-toolbox/tnc-toolbox.php

@@ -5,13 +5,13 @@
  * @package           TNCTOOLBOX
  * @author            The Network Crew Pty Ltd (Merlot Digital)
  * @license           gplv3
- * @version           2.1.0
+ * @version           2.1.1
  *
  * @wordpress-plugin
  * Plugin Name:       TNC Toolbox: Web Performance
  * Plugin URI:        https://merlot.digital
  * Description:       Designed for ea-NGINX (Cache/Proxy) on cPanel+WHM. Now with selective cache purging support!
- * Version:           2.1.0
+ * Version:           2.1.1
  * Author:            The Network Crew Pty Ltd (Merlot Digital)
  * Author URI:        https://tnc.works
  * Domain Path:       /locale

tnc-toolbox/vendor/cache-purge.php

@@ -82,6 +82,12 @@ public static function is_available( $force = false ) {
 	 * PURGE requests must be sent to localhost (127.0.0.1) with the Host header
 	 * set to the actual domain. This is how ea-nginx-cache-purge is configured.
 	 *
+	 * The module returns specific signatures in the response body:
+	 * - HTTP 200 with body containing "Successful purge" = module working.
+	 * - HTTP 412 can occur when item not in cache, but we need body signature.
+	 *
+	 * Without the module, nginx may return 301/404/405 with generic HTML.
+	 *
 	 * @return bool True if PURGE is supported.
 	 */
 	private static function test_purge_capability() {
@@ -111,36 +117,40 @@ private static function test_purge_capability() {
 		$code = wp_remote_retrieve_response_code( $response );
 		$body = wp_remote_retrieve_body( $response );
 
-		// ea-nginx-cache-purge returns:
-		// - 200 OK with "Successful purge" if entry existed.
-		// - 404 Not Found if entry didn't exist (but PURGE is supported).
-		// - 412 Precondition Failed if entry wasn't in cache.
-		// - 405 Method Not Allowed if PURGE is not configured.
-		if ( 200 === $code || 404 === $code || 412 === $code ) {
-			// Check for cache-purge signature in body.
-			if ( stripos( $body, 'purge' ) !== false || stripos( $body, 'cache' ) !== false ) {
-				self::log( 'PURGE test successful: module detected' );
-				return true;
-			}
-			// Even without body, 200/404/412 on PURGE is a good sign.
-			self::log( 'PURGE test: got ' . $code . ', assuming module available' );
+		// ea-nginx-cache-purge module returns specific signatures:
+		// - 200 OK with body "Successful purge" and "Key :" when purged.
+		// - 412 Precondition Failed when item wasn't in cache.
+		//
+		// Without module: 301 redirect, 404 generic HTML, or 405 Method Not Allowed.
+		//
+		// We MUST check body for "Successful purge" signature to confirm module.
+		if ( 200 === $code && stripos( $body, 'Successful purge' ) !== false ) {
+			self::log( 'PURGE test successful: module detected (200 + signature)' );
+			return true;
+		}
+
+		// 412 from module still indicates it's working (item just wasn't cached).
+		// But generic nginx 412 doesn't have our signature, so check for module output.
+		if ( 412 === $code && stripos( $body, 'Precondition Failed' ) !== false ) {
+			// This is likely the module - generic nginx rarely returns 412 for PURGE.
+			self::log( 'PURGE test successful: module detected (412 Precondition Failed)' );
 			return true;
 		}
 
-		self::log( 'PURGE test: got ' . $code . ', module not available' );
+		self::log( 'PURGE test: got HTTP ' . $code . ', module not detected' );
 		return false;
 	}
 
 	/**
 	 * Check if selective purging is enabled.
 	 *
-	 * @return bool True if enabled and available.
+	 * Returns true if the user has enabled selective purging via checkbox.
+	 * Module availability is checked separately during actual purge operations.
+	 *
+	 * @return bool True if enabled by user.
 	 */
 	public static function is_enabled() {
-		$enabled   = get_option( self::OPTION_ENABLED, 'yes' );
-		$available = get_option( self::OPTION_AVAILABLE, 'unknown' );
-
-		return 'yes' === $enabled && 'yes' === $available;
+		return 'yes' === get_option( self::OPTION_ENABLED, 'no' );
 	}
 
 	/**
@@ -207,21 +217,54 @@ public static function purge_url( $url ) {
 		}
 
 		$code = wp_remote_retrieve_response_code( $response );
+		$body = wp_remote_retrieve_body( $response );
 
-		// 200 = successfully purged, 404 = wasn't in cache (ok), 412 = wasn't in cache.
-		if ( 200 === $code || 404 === $code || 412 === $code ) {
-			self::log( 'Purged: ' . $url . ' (HTTP ' . $code . ')' );
+		// ea-nginx-cache-purge module returns:
+		// - 200 with "Successful purge" = item was in cache and purged.
+		// - 412 Precondition Failed = item wasn't in cache (still success).
+		//
+		// Without module: 301/404/405 with generic nginx HTML (not a real purge).
+		if ( 200 === $code && stripos( $body, 'Successful purge' ) !== false ) {
+			self::log( 'Purged: ' . $url . ' (HTTP 200)' );
 			return array(
 				'success' => true,
 				'message' => 'Purged successfully',
 				'code'    => $code,
 			);
 		}
 
+		// 412 means item wasn't cached - that's fine, nothing to purge.
+		if ( 412 === $code ) {
+			self::log( 'Not in cache: ' . $url . ' (HTTP 412)' );
+			return array(
+				'success' => true,
+				'message' => 'Not in cache (already clean)',
+				'code'    => $code,
+			);
+		}
+
+		// Got a 200 but without cache-purge signature = module not working.
+		if ( 200 === $code ) {
+			self::log( 'Purge returned 200 but without module signature for ' . $url );
+			return array(
+				'success' => false,
+				'message' => 'Cache purge module not responding correctly',
+				'code'    => $code,
+			);
+		}
+
+		// 301/404/405 = module not installed or not configured for this domain.
+		$error_msg = 'Purge failed (HTTP ' . $code . ')';
+		if ( 404 === $code || 301 === $code ) {
+			$error_msg = 'Cache purge module not detected - install ea-nginx-cache-purge';
+		} elseif ( 405 === $code ) {
+			$error_msg = 'PURGE method not allowed - cache purge module not configured';
+		}
+
 		self::log( 'Purge failed for ' . $url . ': HTTP ' . $code );
 		return array(
 			'success' => false,
-			'message' => 'Unexpected response: HTTP ' . $code,
+			'message' => $error_msg,
 			'code'    => $code,
 		);
 	}
@@ -466,28 +509,38 @@ private static function log( $message ) {
 	/**
 	 * Get availability status for display.
 	 *
+	 * Detection only runs on settings page (force_recheck=true) to avoid
+	 * HTTP requests on every page load. Admin bar uses cached result.
+	 *
+	 * @param bool $force_recheck Force a fresh detection check (use on settings page).
 	 * @return array Status info with 'available', 'enabled', 'message' keys.
 	 */
-	public static function get_status() {
+	public static function get_status( $force_recheck = false ) {
+		$enabled   = self::is_enabled();
 		$available = get_option( self::OPTION_AVAILABLE, 'unknown' );
-		$enabled   = get_option( self::OPTION_ENABLED, 'yes' );
 
-		if ( 'unknown' === $available ) {
-			$available = self::is_available() ? 'yes' : 'no';
+		// Only recheck on settings page (force_recheck=true).
+		// This avoids HTTP requests on every page load.
+		if ( $force_recheck && $enabled ) {
+			$available = self::is_available( true ) ? 'yes' : 'no';
 		}
 
 		$message = '';
-		if ( 'yes' === $available && 'yes' === $enabled ) {
-			$message = 'Selective purging active — only changed pages are purged for maximum efficiency';
-		} elseif ( 'yes' === $available && 'no' === $enabled ) {
-			$message = 'Selective purging available but disabled';
+		if ( $enabled ) {
+			if ( 'yes' === $available ) {
+				$message = 'Selective purging active — only changed pages are purged for maximum efficiency';
+			} elseif ( 'no' === $available ) {
+				$message = 'Selective purging enabled but module not detected — purges may fail';
+			} else {
+				$message = 'Selective purging enabled — checking module availability...';
+			}
 		} else {
-			$message = 'nginx-module-cache-purge not detected — using full cache purge via cPanel API';
+			$message = 'Selective purging disabled — using full cache purge via cPanel API';
 		}
 
 		return array(
 			'available' => 'yes' === $available,
-			'enabled'   => 'yes' === $enabled,
+			'enabled'   => $enabled,
 			'message'   => $message,
 		);
 	}