Initial Version

shared/lib/Cache/BlobCacheInterface.php

@@ -0,0 +1,123 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXF\Cache;
+
+/**
+ * Blob Cache Interface
+ * 
+ * For binary/media data like preview images, thumbnails, and file caches.
+ * Stored in storage/ rather than var/cache/ due to larger sizes and user ownership.
+ * 
+ * Use cases: contact previews, file thumbnails, generated images.
+ */
+interface BlobCacheInterface
+{
+    /**
+     * Default TTL for blob cache entries (7 days)
+     */
+    public const DEFAULT_TTL = 604800;
+
+    /**
+     * Get blob data as a string
+     * 
+     * @param string $key Cache key
+     * @param CacheScope $scope Cache scope level
+     * @param string $usage Usage/bucket name (e.g., 'previews', 'thumbnails')
+     * @return string|null Blob data or null if not found
+     */
+    public function get(string $key, CacheScope $scope, string $usage): ?string;
+
+    /**
+     * Get blob data as a stream resource
+     * 
+     * @param string $key Cache key
+     * @param CacheScope $scope Cache scope level
+     * @param string $usage Usage/bucket name
+     * @return resource|null Stream resource or null if not found
+     */
+    public function getStream(string $key, CacheScope $scope, string $usage);
+
+    /**
+     * Store blob data from a string
+     * 
+     * @param string $key Cache key
+     * @param string $data Blob data
+     * @param CacheScope $scope Cache scope level
+     * @param string $usage Usage/bucket name
+     * @param string|null $mimeType MIME type of the blob
+     * @param int|null $ttl Time-to-live in seconds
+     * @return bool True if stored successfully
+     */
+    public function set(string $key, string $data, CacheScope $scope, string $usage, ?string $mimeType = null, ?int $ttl = null): bool;
+
+    /**
+     * Store blob data from a stream
+     * 
+     * @param string $key Cache key
+     * @param resource $stream Stream resource to read from
+     * @param CacheScope $scope Cache scope level
+     * @param string $usage Usage/bucket name
+     * @param string|null $mimeType MIME type of the blob
+     * @param int|null $ttl Time-to-live in seconds
+     * @return bool True if stored successfully
+     */
+    public function putStream(string $key, $stream, CacheScope $scope, string $usage, ?string $mimeType = null, ?int $ttl = null): bool;
+
+    /**
+     * Check if a blob exists
+     * 
+     * @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;
+
+    /**
+     * Delete a blob
+     * 
+     * @param string $key Cache key
+     * @param CacheScope $scope Cache scope level
+     * @param string $usage Usage/bucket name
+     * @return bool True if deleted
+     */
+    public function delete(string $key, CacheScope $scope, string $usage): bool;
+
+    /**
+     * Get the local filesystem path to a blob (if available)
+     * 
+     * @param string $key Cache key
+     * @param CacheScope $scope Cache scope level
+     * @param string $usage Usage/bucket name
+     * @return string|null Filesystem path or null if not available/not local
+     */
+    public function getPath(string $key, CacheScope $scope, string $usage): ?string;
+
+    /**
+     * Get metadata for a blob
+     * 
+     * @param string $key Cache key
+     * @param CacheScope $scope Cache scope level
+     * @param string $usage Usage/bucket name
+     * @return array{mimeType: string|null, size: int, createdAt: int, expiresAt: int|null}|null
+     */
+    public function getMetadata(string $key, CacheScope $scope, string $usage): ?array;
+
+    /**
+     * Clear all blobs in a usage bucket
+     * 
+     * @param CacheScope $scope Cache scope level
+     * @param string $usage Usage/bucket name
+     * @return int Number of blobs removed
+     */
+    public function clear(CacheScope $scope, string $usage): int;
+
+    /**
+     * Clean up expired blobs
+     * 
+     * @return int Number of blobs cleaned up
+     */
+    public function cleanup(): int;
+}