Initial Version

shared/lib/Cache/PersistentCacheInterface.php

@@ -0,0 +1,66 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXF\Cache;
+
+/**
+ * Persistent Cache Interface
+ * 
+ * For long-lived cached data with optional tagging for bulk invalidation.
+ * Use cases: routes, modules, compiled configs, firewall rules.
+ * 
+ * Default TTL is typically hours to days, or indefinite until explicit invalidation.
+ */
+interface PersistentCacheInterface extends CacheInterface
+{
+    /**
+     * Default TTL for persistent cache entries (1 hour)
+     * Use 0 for indefinite storage
+     */
+    public const DEFAULT_TTL = 3600;
+
+    /**
+     * Store an item with tags for bulk invalidation
+     * 
+     * @param string $key Cache key
+     * @param mixed $value Value to cache
+     * @param CacheScope $scope Cache scope level
+     * @param string $usage Usage/bucket name
+     * @param array<string> $tags Tags for grouping/invalidation
+     * @param int|null $ttl Time-to-live in seconds (null = default, 0 = indefinite)
+     * @return bool True if stored successfully
+     */
+    public function setWithTags(string $key, mixed $value, CacheScope $scope, string $usage, array $tags, ?int $ttl = null): bool;
+
+    /**
+     * Invalidate all entries with a specific tag
+     * 
+     * @param string $tag Tag to invalidate
+     * @param CacheScope $scope Cache scope level
+     * @param string $usage Usage/bucket name
+     * @return int Number of entries invalidated
+     */
+    public function invalidateByTag(string $tag, CacheScope $scope, string $usage): int;
+
+    /**
+     * Get the version/timestamp of a cached entry
+     * 
+     * @param string $key Cache key
+     * @param CacheScope $scope Cache scope level
+     * @param string $usage Usage/bucket name
+     * @return int|null Timestamp when entry was cached, or null if not found
+     */
+    public function getVersion(string $key, CacheScope $scope, string $usage): ?int;
+
+    /**
+     * Check if an entry is stale based on a reference timestamp
+     * 
+     * @param string $key Cache key
+     * @param CacheScope $scope Cache scope level
+     * @param string $usage Usage/bucket name
+     * @param int $reference Reference timestamp to compare against
+     * @return bool True if entry is older than reference (or doesn't exist)
+     */
+    public function isStale(string $key, CacheScope $scope, string $usage, int $reference): bool;
+}