Initial Version

shared/lib/Cache/EphemeralCacheInterface.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXF\Cache;
+
+/**
+ * Ephemeral Cache Interface
+ * 
+ * For short-lived cached data with automatic expiration.
+ * Use cases: sessions, rate limits, challenges, temporary config.
+ * 
+ * Default TTL is typically seconds to minutes.
+ */
+interface EphemeralCacheInterface extends CacheInterface
+{
+    /**
+     * Default TTL for ephemeral cache entries (5 minutes)
+     */
+    public const DEFAULT_TTL = 300;
+
+    /**
+     * Get or set a value with a callback
+     * 
+     * If the key doesn't exist, execute the callback and cache the result.
+     * 
+     * @param string $key Cache key
+     * @param callable $callback Function to generate value if not cached
+     * @param CacheScope $scope Cache scope level
+     * @param string $usage Usage/bucket name
+     * @param int|null $ttl Time-to-live in seconds
+     * @return mixed Cached or generated value
+     */
+    public function remember(string $key, callable $callback, CacheScope $scope, string $usage, ?int $ttl = null): mixed;
+
+    /**
+     * Increment a numeric value
+     * 
+     * @param string $key Cache key
+     * @param CacheScope $scope Cache scope level
+     * @param string $usage Usage/bucket name
+     * @param int $amount Amount to increment by
+     * @return int|false New value or false on failure
+     */
+    public function increment(string $key, CacheScope $scope, string $usage, int $amount = 1): int|false;
+
+    /**
+     * Decrement a numeric value
+     * 
+     * @param string $key Cache key
+     * @param CacheScope $scope Cache scope level
+     * @param string $usage Usage/bucket name
+     * @param int $amount Amount to decrement by
+     * @return int|false New value or false on failure
+     */
+    public function decrement(string $key, CacheScope $scope, string $usage, int $amount = 1): int|false;
+}