124 lines
3.9 KiB
PHP
124 lines
3.9 KiB
PHP
<?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;
|
|
}
|