[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  declare (strict_types=1);
   4  namespace WordPress\AiClient\Common\Traits;
   5  
   6  use WordPress\AiClient\AiClient;
   7  /**
   8   * Trait for objects that cache data using PSR-16 cache with in-memory fallback.
   9   *
  10   * When a PSR-16 cache is configured via AiClient::setCache(), data is stored persistently.
  11   * Otherwise, data is cached in-memory for the duration of the request.
  12   *
  13   * @since 0.4.0
  14   */
  15  trait WithDataCachingTrait
  16  {
  17      /**
  18       * In-memory cache used when no PSR-16 cache is configured.
  19       *
  20       * @since 0.4.0
  21       *
  22       * @var array<string, mixed>
  23       */
  24      private array $localCache = [];
  25      /**
  26       * Gets the cache key suffixes managed by this object.
  27       *
  28       * @since 0.4.0
  29       *
  30       * @return list<string> The cache key suffixes.
  31       */
  32      abstract protected function getCachedKeys(): array;
  33      /**
  34       * Gets the base cache key for this object.
  35       *
  36       * The base cache key is used as a prefix for all cache keys managed by this object.
  37       * It should be unique to the implementing class to avoid cache key collisions.
  38       *
  39       * @since 0.4.0
  40       *
  41       * @return string The base cache key.
  42       */
  43      abstract protected function getBaseCacheKey(): string;
  44      /**
  45       * Checks if a value exists in the cache.
  46       *
  47       * @since 0.4.0
  48       *
  49       * @param string $key The cache key suffix (will be appended to the base key).
  50       * @return bool True if the value exists in cache, false otherwise.
  51       */
  52      protected function hasCache(string $key): bool
  53      {
  54          $fullKey = $this->buildCacheKey($key);
  55          $cache = AiClient::getCache();
  56          if ($cache !== null) {
  57              return $cache->has($fullKey);
  58          }
  59          return array_key_exists($fullKey, $this->localCache);
  60      }
  61      /**
  62       * Gets a value from the cache, or computes and caches it if not present.
  63       *
  64       * @since 0.4.0
  65       *
  66       * @param string                 $key      The cache key suffix (will be appended to the base key).
  67       * @param callable               $callback The callback to compute the value if not cached.
  68       * @param int|\DateInterval|null $ttl      The TTL for the cache entry, or null for default.
  69       *                                         Ignored for local cache.
  70       * @return mixed The cached or computed value.
  71       */
  72      protected function cached(string $key, callable $callback, $ttl = null)
  73      {
  74          if ($this->hasCache($key)) {
  75              return $this->getCache($key);
  76          }
  77          $value = $callback();
  78          $this->setCache($key, $value, $ttl);
  79          return $value;
  80      }
  81      /**
  82       * Gets a value from the cache.
  83       *
  84       * @since 0.4.0
  85       *
  86       * @param string $key     The cache key suffix (will be appended to the base key).
  87       * @param mixed  $default The default value to return if the key does not exist.
  88       * @return mixed The cached value or the default value if not found.
  89       */
  90      protected function getCache(string $key, $default = null)
  91      {
  92          $fullKey = $this->buildCacheKey($key);
  93          $cache = AiClient::getCache();
  94          if ($cache !== null) {
  95              return $cache->get($fullKey, $default);
  96          }
  97          return $this->localCache[$fullKey] ?? $default;
  98      }
  99      /**
 100       * Sets a value in the cache.
 101       *
 102       * @since 0.4.0
 103       *
 104       * @param string                $key   The cache key suffix (will be appended to the base key).
 105       * @param mixed                 $value The value to cache.
 106       * @param int|\DateInterval|null $ttl   The TTL for the cache entry, or null for default. Ignored for local cache.
 107       * @return bool True on success, false on failure.
 108       */
 109      protected function setCache(string $key, $value, $ttl = null): bool
 110      {
 111          $fullKey = $this->buildCacheKey($key);
 112          $cache = AiClient::getCache();
 113          if ($cache !== null) {
 114              return $cache->set($fullKey, $value, $ttl);
 115          }
 116          $this->localCache[$fullKey] = $value;
 117          return \true;
 118      }
 119      /**
 120       * Invalidates all caches managed by this object.
 121       *
 122       * @since 0.4.0
 123       *
 124       * @return void
 125       */
 126      public function invalidateCaches(): void
 127      {
 128          foreach ($this->getCachedKeys() as $key) {
 129              $this->clearCache($key);
 130          }
 131      }
 132      /**
 133       * Clears a value from the cache.
 134       *
 135       * @since 0.4.0
 136       *
 137       * @param string $key The cache key suffix (will be appended to the base key).
 138       * @return bool True on success, false on failure.
 139       */
 140      protected function clearCache(string $key): bool
 141      {
 142          $fullKey = $this->buildCacheKey($key);
 143          $cache = AiClient::getCache();
 144          if ($cache !== null) {
 145              return $cache->delete($fullKey);
 146          }
 147          unset($this->localCache[$fullKey]);
 148          return \true;
 149      }
 150      /**
 151       * Builds the full cache key by combining the base key with the suffix.
 152       *
 153       * @since 0.4.0
 154       *
 155       * @param string $key The cache key suffix.
 156       * @return string The full cache key.
 157       */
 158      private function buildCacheKey(string $key): string
 159      {
 160          return $this->getBaseCacheKey() . '_' . $key;
 161      }
 162  }