<?php
declare (strict_types=1);
namespace WordPress\AiClient\Common\Traits;
use WordPress\AiClient\AiClient;
/**
* Trait for objects that cache data using PSR-16 cache with in-memory fallback.
*
* When a PSR-16 cache is configured via AiClient::setCache(), data is stored persistently.
* Otherwise, data is cached in-memory for the duration of the request.
*
* @since 0.4.0
*/
trait WithDataCachingTrait
{
/**
* In-memory cache used when no PSR-16 cache is configured.
*
* @since 0.4.0
*
* @var array<string, mixed>
*/
private array $localCache = [];
/**
* Gets the cache key suffixes managed by this object.
*
* @since 0.4.0
*
* @return list<string> The cache key suffixes.
*/
abstract protected function getCachedKeys(): array;
/**
* Gets the base cache key for this object.
*
* The base cache key is used as a prefix for all cache keys managed by this object.
* It should be unique to the implementing class to avoid cache key collisions.
*
* @since 0.4.0
*
* @return string The base cache key.
*/
abstract protected function getBaseCacheKey(): string;
/**
* Checks if a value exists in the cache.
*
* @since 0.4.0
*
* @param string $key The cache key suffix (will be appended to the base key).
* @return bool True if the value exists in cache, false otherwise.
*/
protected function hasCache(string $key): bool
{
$fullKey = $this->buildCacheKey($key);
$cache = AiClient::getCache();
if ($cache !== null) {
return $cache->has($fullKey);
}
return array_key_exists($fullKey, $this->localCache);
}
/**
* Gets a value from the cache, or computes and caches it if not present.
*
* @since 0.4.0
*
* @param string $key The cache key suffix (will be appended to the base key).
* @param callable $callback The callback to compute the value if not cached.
* @param int|\DateInterval|null $ttl The TTL for the cache entry, or null for default.
* Ignored for local cache.
* @return mixed The cached or computed value.
*/
protected function cached(string $key, callable $callback, $ttl = null)
{
if ($this->hasCache($key)) {
return $this->getCache($key);
}
$value = $callback();
$this->setCache($key, $value, $ttl);
return $value;
}
/**
* Gets a value from the cache.
*
* @since 0.4.0
*
* @param string $key The cache key suffix (will be appended to the base key).
* @param mixed $default The default value to return if the key does not exist.
* @return mixed The cached value or the default value if not found.
*/
protected function getCache(string $key, $default = null)
{
$fullKey = $this->buildCacheKey($key);
$cache = AiClient::getCache();
if ($cache !== null) {
return $cache->get($fullKey, $default);
}
return $this->localCache[$fullKey] ?? $default;
}
/**
* Sets a value in the cache.
*
* @since 0.4.0
*
* @param string $key The cache key suffix (will be appended to the base key).
* @param mixed $value The value to cache.
* @param int|\DateInterval|null $ttl The TTL for the cache entry, or null for default. Ignored for local cache.
* @return bool True on success, false on failure.
*/
protected function setCache(string $key, $value, $ttl = null): bool
{
$fullKey = $this->buildCacheKey($key);
$cache = AiClient::getCache();
if ($cache !== null) {
return $cache->set($fullKey, $value, $ttl);
}
$this->localCache[$fullKey] = $value;
return \true;
}
/**
* Invalidates all caches managed by this object.
*
* @since 0.4.0
*
* @return void
*/
public function invalidateCaches(): void
{
foreach ($this->getCachedKeys() as $key) {
$this->clearCache($key);
}
}
/**
* Clears a value from the cache.
*
* @since 0.4.0
*
* @param string $key The cache key suffix (will be appended to the base key).
* @return bool True on success, false on failure.
*/
protected function clearCache(string $key): bool
{
$fullKey = $this->buildCacheKey($key);
$cache = AiClient::getCache();
if ($cache !== null) {
return $cache->delete($fullKey);
}
unset($this->localCache[$fullKey]);
return \true;
}
/**
* Builds the full cache key by combining the base key with the suffix.
*
* @since 0.4.0
*
* @param string $key The cache key suffix.
* @return string The full cache key.
*/
private function buildCacheKey(string $key): string
{
return $this->getBaseCacheKey() . '_' . $key;
}
}