Initial Version

shared/lib/Cache/CacheInterface.php

@@ -0,0 +1,72 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXF\Cache;
+
+/**
+ * Base Cache Interface
+ * 
+ * Common interface for all cache implementations.
+ * Supports scoped caching with automatic key prefixing based on scope.
+ */
+interface CacheInterface
+{
+    /**
+     * Retrieve an item from the cache
+     * 
+     * @param string $key Cache key
+     * @param CacheScope $scope Cache scope level
+     * @param string $usage Usage/bucket name (e.g., 'sessions', 'config')
+     * @return mixed|null Cached value or null if not found/expired
+     */
+    public function get(string $key, CacheScope $scope, string $usage): mixed;
+
+    /**
+     * Store an item in the cache
+     * 
+     * @param string $key Cache key
+     * @param mixed $value Value to cache (must be serializable)
+     * @param CacheScope $scope Cache scope level
+     * @param string $usage Usage/bucket name
+     * @param int|null $ttl Time-to-live in seconds (null = default, 0 = indefinite)
+     * @return bool True if stored successfully
+     */
+    public function set(string $key, mixed $value, CacheScope $scope, string $usage, ?int $ttl = null): bool;
+
+    /**
+     * Check if an item exists in the cache
+     * 
+     * @param string $key Cache key
+     * @param CacheScope $scope Cache scope level
+     * @param string $usage Usage/bucket name
+     * @return bool True if exists and not expired
+     */
+    public function has(string $key, CacheScope $scope, string $usage): bool;
+
+    /**
+     * Remove an item from the cache
+     * 
+     * @param string $key Cache key
+     * @param CacheScope $scope Cache scope level
+     * @param string $usage Usage/bucket name
+     * @return bool True if deleted (or didn't exist)
+     */
+    public function delete(string $key, CacheScope $scope, string $usage): bool;
+
+    /**
+     * Remove all items matching a usage pattern
+     * 
+     * @param CacheScope $scope Cache scope level
+     * @param string $usage Usage/bucket name
+     * @return int Number of items removed
+     */
+    public function clear(CacheScope $scope, string $usage): int;
+
+    /**
+     * Clean up expired entries
+     * 
+     * @return int Number of entries cleaned up
+     */
+    public function cleanup(): int;
+}