feat: add cache expiry and timestamp-based validation to Knowledge Base caching system

Author: ajaydsouza

includes/util/class-cache.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * Cache functions used by Better Search
+ * Cache functions used by Knowledge Base
  *
  * @since 2.3.0
  *
@@ -32,7 +32,7 @@ public function __construct() {
 	}
 
 	/**
-	 * Function to clear the Better Search Cache with Ajax.
+	 * Function to clear the Knowledge Base Cache with Ajax.
 	 *
 	 * @since 2.3.0
 	 */
@@ -43,7 +43,7 @@ public function ajax_clearcache() {
 		}
 		check_ajax_referer( 'wzkb-admin', 'security' );
 
-		$count = $this->delete();
+		$count = self::delete();
 
 		wp_send_json_success(
 			array(
@@ -56,7 +56,7 @@ public function ajax_clearcache() {
 	}
 
 	/**
-	 * Delete the Better Search cache.
+	 * Delete the Knowledge Base cache.
 	 *
 	 * @since 2.3.0
 	 *
@@ -133,4 +133,122 @@ public static function get_key( $attr ) {
 
 		return $meta_key;
 	}
+
+	/**
+	 * Get the timestamp meta key for a cache entry.
+	 *
+	 * @since 3.0.0
+	 *
+	 * @param string $cache_key The cache key.
+	 * @return string Timestamp meta key
+	 */
+	public static function get_timestamp_key( $cache_key ) {
+		return $cache_key . '_timestamp';
+	}
+
+	/**
+	 * Check if a cache entry has expired.
+	 *
+	 * @since 3.0.0
+	 *
+	 * @param int    $term_id   Term ID.
+	 * @param string $cache_key Cache key.
+	 * @return bool True if expired or no expiry set, false if still valid.
+	 */
+	public static function is_expired( $term_id, $cache_key ) {
+		$cache_expiry = (int) \wzkb_get_option( 'cache_expiry', DAY_IN_SECONDS );
+
+		// If expiry is 0, cache never expires.
+		if ( 0 === $cache_expiry ) {
+			return false;
+		}
+
+		$timestamp_key = self::get_timestamp_key( $cache_key );
+		$cached_time   = get_term_meta( $term_id, $timestamp_key, true );
+
+		// If no timestamp exists, consider it expired.
+		if ( false === $cached_time || '' === $cached_time ) {
+			return true;
+		}
+
+		$cached_time = (int) $cached_time;
+
+		$expiry_time = $cached_time + $cache_expiry;
+
+		return time() > $expiry_time;
+	}
+
+	/**
+	 * Store cache data with timestamp.
+	 *
+	 * @since 3.0.0
+	 *
+	 * @param int    $term_id   Term ID.
+	 * @param string $cache_key Cache key.
+	 * @param mixed  $data      Data to cache.
+	 * @return bool True on success, false on failure.
+	 */
+	public static function set( $term_id, $cache_key, $data ) {
+		$timestamp_key = self::get_timestamp_key( $cache_key );
+
+		// Delete existing cache entries first to ensure clean update.
+		delete_term_meta( $term_id, $cache_key );
+		delete_term_meta( $term_id, $timestamp_key );
+
+		// Store timestamp first to ensure atomicity.
+		$timestamp_stored = add_term_meta( $term_id, $timestamp_key, time(), true );
+
+		// Only store data if timestamp was successfully stored.
+		if ( ! $timestamp_stored ) {
+			return false;
+		}
+
+		$data_stored = add_term_meta( $term_id, $cache_key, $data, true );
+
+		// If data storage fails, clean up the orphaned timestamp.
+		if ( ! $data_stored ) {
+			delete_term_meta( $term_id, $timestamp_key );
+			return false;
+		}
+
+		return true;
+	}
+
+	/**
+	 * Get cache data if not expired.
+	 *
+	 * @since 3.0.0
+	 *
+	 * @param int    $term_id   Term ID.
+	 * @param string $cache_key Cache key.
+	 * @return mixed|false Cached data if valid, false if expired or not found.
+	 */
+	public static function get( $term_id, $cache_key ) {
+		// Check if cache has expired.
+		if ( self::is_expired( $term_id, $cache_key ) ) {
+			// Clean up expired cache.
+			self::delete_expired_entry( $term_id, $cache_key );
+			return false;
+		}
+
+		return get_term_meta( $term_id, $cache_key, true );
+	}
+
+	/**
+	 * Delete an expired cache entry and its timestamp.
+	 *
+	 * @since 3.0.0
+	 *
+	 * @param int    $term_id   Term ID.
+	 * @param string $cache_key Cache key.
+	 * @return bool True on success, false on failure.
+	 */
+	public static function delete_expired_entry( $term_id, $cache_key ) {
+		$timestamp_key = self::get_timestamp_key( $cache_key );
+
+		$data_deleted      = delete_term_meta( $term_id, $cache_key );
+		$timestamp_deleted = delete_term_meta( $term_id, $timestamp_key );
+
+		return $data_deleted || $timestamp_deleted;
+	}
 }